From bae3a863d424b96e01f1698ede22cf0e7e929a5c Mon Sep 17 00:00:00 2001 From: Peter Occil Date: Sun, 3 Nov 2024 10:52:12 -0500 Subject: [PATCH] edit docs; etc. --- CBOR.nuspec | 2 +- CBORTest/CBORTest.csproj | 2 +- docs/APIDocs.md | 2 + docs/PeterO.Cbor.CBORDataUtilities.md | 67 +- docs/PeterO.Cbor.CBORDateConverter.md | 7 + docs/PeterO.Cbor.CBORNumber.md | 17 - docs/PeterO.Cbor.CBORObject.md | 1758 +++++++++++++++---------- docs/PeterO.Cbor.JSONOptions.md | 2 +- docs/PeterO.Cbor.PODOptions.md | 2 +- docs/PeterO.DataUtilities.md | 661 ++++++++++ 10 files changed, 1773 insertions(+), 747 deletions(-) diff --git a/CBOR.nuspec b/CBOR.nuspec index 3de875b0..7e95ec7f 100644 --- a/CBOR.nuspec +++ b/CBOR.nuspec @@ -14,4 +14,4 @@ Version 4.5: - Add support for deserializing CBOR objects to IReadOnlyList, IReadOnlyCollection, and ReadOnlyDictionary Note that after version 4.5x, the CBOR library's repository will stop including special projects for .NET 2.0 and .NET 4.0, leaving the .NET-Standard project for building the library.Unlicensehttps://github.com/peteroupc/CBORPeter OccilA C# implementation of Concise Binary Object Representation (CBOR), a general-purpose binary data format defined in RFC 8949.Peter OccilCBOR (Concise Binary Object Representation)cbor data serialization binary json \ No newline at end of file +> diff --git a/CBORTest/CBORTest.csproj b/CBORTest/CBORTest.csproj index c600a810..dbbaa48e 100644 --- a/CBORTest/CBORTest.csproj +++ b/CBORTest/CBORTest.csproj @@ -1,6 +1,6 @@ - netcoreapp7.0 + netcoreapp8.0 full diff --git a/docs/APIDocs.md b/docs/APIDocs.md index 0aa5db49..ac41af33 100644 --- a/docs/APIDocs.md +++ b/docs/APIDocs.md @@ -29,3 +29,5 @@ * [PeterO.Cbor.JSONOptions.ConversionMode](PeterO.Cbor.JSONOptions.ConversionMode.md) - Specifies how JSON numbers are converted to CBOR objects when decoding JSON (such as via FromJSONString or ReadJSON ). * [PeterO.Cbor.PODOptions](PeterO.Cbor.PODOptions.md) - Options for controlling how certain DotNET or Java objects, such as so-called "plain old data" objects (better known as POCOs in DotNET or POJOs in Java), are converted to CBOR objects. + + * [PeterO.DataUtilities](PeterO.DataUtilities.md) - Contains methods useful for reading and writing text strings. diff --git a/docs/PeterO.Cbor.CBORDataUtilities.md b/docs/PeterO.Cbor.CBORDataUtilities.md index ad821e69..7cd763ca 100644 --- a/docs/PeterO.Cbor.CBORDataUtilities.md +++ b/docs/PeterO.Cbor.CBORDataUtilities.md @@ -14,6 +14,8 @@ Contains methods useful for reading and writing data, with a focus on CBOR. * [ParseJSONNumber(char[], int, int, PeterO.Cbor.JSONOptions)](#ParseJSONNumber_char_int_int_PeterO_Cbor_JSONOptions) - Parses a number from a sequence of char s whose format follows the JSON specification (RFC 8259) and converts that number to a CBOR object. * [ParseJSONNumber(char[], PeterO.Cbor.JSONOptions)](#ParseJSONNumber_char_PeterO_Cbor_JSONOptions) - Parses a number from a sequence of char s whose format follows the JSON specification (RFC 8259) and converts that number to a CBOR object. * [ParseJSONNumber(string)](#ParseJSONNumber_string) - Parses a number whose format follows the JSON specification. +* [ParseJSONNumber(string, bool, bool)](#ParseJSONNumber_string_bool_bool) - Deprecated: Call the one-argument version of this method instead. If this method call used positiveOnly = true, check that the string does not begin with '-' before calling that version. If this method call used integersOnly = true, check that the string does not contain '.', 'E', or 'e' before calling that version. +* [ParseJSONNumber(string, bool, bool, bool)](#ParseJSONNumber_string_bool_bool_bool) - Deprecated: Instead, call ParseJSONNumber(str, jsonoptions) with a JSONOptions that sets preserveNegativeZero to the desired value, either true or false. If this method call used positiveOnly = true, check that the string does not begin with '-' before calling that version. If this method call used integersOnly = true, check that the string does not contain '.', 'E', or 'e' before calling that version. * [ParseJSONNumber(string, int, int)](#ParseJSONNumber_string_int_int) - Parses a number whose format follows the JSON specification (RFC 8259) from a portion of a text string, and converts that number to a CBOR object. * [ParseJSONNumber(string, int, int, PeterO.Cbor.JSONOptions)](#ParseJSONNumber_string_int_int_PeterO_Cbor_JSONOptions) - Parses a number whose format follows the JSON specification (RFC 8259) and converts that number to a CBOR object. * [ParseJSONNumber(string, PeterO.Cbor.JSONOptions)](#ParseJSONNumber_string_PeterO_Cbor_JSONOptions) - Parses a number whose format follows the JSON specification (RFC 8259) and converts that number to a CBOR object. @@ -24,7 +26,7 @@ Contains methods useful for reading and writing data, with a focus on CBOR. public static PeterO.Cbor.CBORObject ParseJSONNumber( byte[] bytes); -Parses a number from a byte sequence whose format follows the JSON specification. The method uses a JSONOptions with all default properties. +Parses a number from a byte sequence whose format follows the JSON specification. The method uses a JSONOptions with all default properties except for a PreserveNegativeZero property of false. Parameters: @@ -32,7 +34,7 @@ Parses a number from a byte sequence whose format follows the JSON specification Return Value: -A CBOR object that represents the parsed number. Returns null if the parsing fails, including if the byte sequence is null or empty. +A CBOR object that represents the parsed number. Returns positive zero if the number is a zero that starts with a minus sign (such as "-0" or "-0.0"). Returns null if the parsing fails, including if the byte sequence is null or empty. ### ParseJSONNumber @@ -143,7 +145,7 @@ A CBOR object that represents the parsed number. Returns null if the parsing fai public static PeterO.Cbor.CBORObject ParseJSONNumber( char[] chars); -Parses a number from a sequence of `char` s whose format follows the JSON specification. The method uses a JSONOptions with all default properties. +Parses a number from a sequence of `char` s whose format follows the JSON specification. The method uses a JSONOptions with all default properties except for a PreserveNegativeZero property of false. Parameters: @@ -151,7 +153,7 @@ Parses a number from a sequence of `char` s whose format follows the JSON spec Return Value: -A CBOR object that represents the parsed number. Returns null if the parsing fails, including if the sequence of `char` s is null or empty. +A CBOR object that represents the parsed number. Returns positive zero if the number is a zero that starts with a minus sign (such as "-0" or "-0.0"). Returns null if the parsing fails, including if the sequence of `char` s is null or empty. ### ParseJSONNumber @@ -262,12 +264,67 @@ A CBOR object that represents the parsed number. Returns null if the parsing fai public static PeterO.Cbor.CBORObject ParseJSONNumber( string str); -Parses a number whose format follows the JSON specification. The method uses a JSONOptions with all default properties. +Parses a number whose format follows the JSON specification. The method uses a JSONOptions with all default properties except for a PreserveNegativeZero property of false. + +Parameters: + + * str: A text string to parse as a JSON number. + +Return Value: + +A CBOR object that represents the parsed number. Returns positive zero if the number is a zero that starts with a minus sign (such as "-0" or "-0.0"). Returns null if the parsing fails, including if the string is null or empty. + + +### ParseJSONNumber + + public static PeterO.Cbor.CBORObject ParseJSONNumber( + string str, + bool integersOnly, + bool positiveOnly); + +Deprecated. Call the one-argument version of this method instead. If this method call used positiveOnly = true, check that the string does not begin with '-' before calling that version. If this method call used integersOnly = true, check that the string does not contain '.', 'E', or 'e' before calling that version. + +Parses a number whose format follows the JSON specification (RFC 8259). The method uses a JSONOptions with all default properties except for a PreserveNegativeZero property of false. + +Roughly speaking, a valid JSON number consists of an optional minus sign, one or more basic digits (starting with 1 to 9 unless there is only one digit and that digit is 0), an optional decimal point (".", full stop) with one or more basic digits, and an optional letter E or e with an optional plus or minus sign and one or more basic digits (the exponent). A text string representing a valid JSON number is not allowed to contain white space characters, including spaces. Parameters: * str: A text string to parse as a JSON number. + * integersOnly: If true, no decimal points or exponents are allowed in the string. The default is false. + + * positiveOnly: If true, only positive numbers are allowed (the leading minus is disallowed). The default is false. + +Return Value: + +A CBOR object that represents the parsed number. Returns positive zero if the number is a zero that starts with a minus sign (such as "-0" or "-0.0"). Returns null if the parsing fails, including if the string is null or empty. + + +### ParseJSONNumber + + public static PeterO.Cbor.CBORObject ParseJSONNumber( + string str, + bool integersOnly, + bool positiveOnly, + bool preserveNegativeZero); + +Deprecated. Instead, call ParseJSONNumber(str, jsonoptions) with a JSONOptions that sets preserveNegativeZero to the desired value, either true or false. If this method call used positiveOnly = true, check that the string does not begin with '-' before calling that version. If this method call used integersOnly = true, check that the string does not contain '.', 'E', or 'e' before calling that version. + +Parses a number whose format follows the JSON specification (RFC 8259). + +Roughly speaking, a valid JSON number consists of an optional minus sign, one or more basic digits (starting with 1 to 9 unless there is only one digit and that digit is 0), an optional decimal point (".", full stop) with one or more basic digits, and an optional letter E or e with an optional plus or minus sign and one or more basic digits (the exponent). A text string representing a valid JSON number is not allowed to contain white space characters, including spaces. + +Parameters: + + * str: A text string to parse as a JSON number. + + * integersOnly: If true, no decimal points or exponents are allowed in the string. The default is false. + + * positiveOnly: If true, the leading minus is disallowed in the string. The default is false. + + * preserveNegativeZero: If true, returns positive zero if the number is a zero that starts with a minus sign (such as "-0" or "-0.0"). Otherwise, returns negative zero in this case. The default is false. + Return Value: A CBOR object that represents the parsed number. Returns null if the parsing fails, including if the string is null or empty. diff --git a/docs/PeterO.Cbor.CBORDateConverter.md b/docs/PeterO.Cbor.CBORDateConverter.md index 8d4fd9d9..b9dd76a9 100644 --- a/docs/PeterO.Cbor.CBORDateConverter.md +++ b/docs/PeterO.Cbor.CBORDateConverter.md @@ -298,3 +298,10 @@ Tries to extract the fields of a date and time in the form of a CBOR object. Return Value: Either `true` if the method is successful, or `false` otherwise. + +Exceptions: + + * System.ArgumentNullException: +The parameter year + or lesserFields + is null, or contains fewer elements than required. diff --git a/docs/PeterO.Cbor.CBORNumber.md b/docs/PeterO.Cbor.CBORNumber.md index 68a8120f..d348398f 100644 --- a/docs/PeterO.Cbor.CBORNumber.md +++ b/docs/PeterO.Cbor.CBORNumber.md @@ -45,7 +45,6 @@ An instance of a number that CBOR or certain CBOR tags can represent. For this p * [ToByteIfExact()](#ToByteIfExact) - Converts this number's value to a byte (from 0 to 255) if it can fit in a byte (from 0 to 255) without rounding to a different numerical value. * [ToByteUnchecked()](#ToByteUnchecked) - Converts this number's value to an integer by discarding its fractional part, and returns the least-significant bits of its two's-complement form as a byte (from 0 to 255). * [ToCBORObject()](#ToCBORObject) - Converts this object's value to a CBOR object. -* [ToDecimal()](#ToDecimal) - Converts this number's value to a CLR decimal. * [ToEDecimal()](#ToEDecimal) - Converts this object to a decimal number. * [ToEFloat()](#ToEFloat) - Converts this object to an arbitrary-precision binary floating point number. * [ToEInteger()](#ToEInteger) - Converts this object to an arbitrary-precision integer. @@ -678,22 +677,6 @@ Converts this object's value to a CBOR object. A CBOR object that stores this object's value. - -### ToDecimal - - public decimal ToDecimal(); - -Converts this number's value to a CLR decimal. - -Return Value: - -This number's value, converted to a decimal as though by `(decimal)this.ToEDecimal()` . - -Exceptions: - - * System.OverflowException: -This value is infinity or not-a-number. - ### ToEDecimal diff --git a/docs/PeterO.Cbor.CBORObject.md b/docs/PeterO.Cbor.CBORObject.md index 9bccbd4b..5851f4ab 100644 --- a/docs/PeterO.Cbor.CBORObject.md +++ b/docs/PeterO.Cbor.CBORObject.md @@ -14,7 +14,7 @@ There are many ways to get a CBOR object, including from bytes, objects, streams To and from data streams: The CBORObject.Write methods write many kinds of objects to a data stream, including numbers, CBOR objects, strings, and arrays of numbers and strings. The CBORObject.Read method reads a CBOR object from a data stream. -To and from other objects: The `CBORObject.From[Type]` method converts many kinds of objects to a CBOR object, including numbers, strings, and arrays and maps of numbers and strings. Methods like AsNumber and AsString convert a CBOR object to different types of object. The `CBORObject.ToObject` method converts a CBOR object to an object of a given type; for example, a CBOR array to a native `List` (or `ArrayList` in Java), or a CBOR integer to an `int` or `long` . Of these methods, the.NET versions of the methods `CBORObject.FromObject` and `CBORObject.ToObject` are not compatible with any context that disallows reflection, such as ahead-of-time compilation or self-contained app deployment. +To and from other objects: The `CBORObject.FromObject` method converts many kinds of objects to a CBOR object, including numbers, strings, and arrays and maps of numbers and strings. Methods like AsNumber and AsString convert a CBOR object to different types of object. The `CBORObject.ToObject` method converts a CBOR object to an object of a given type; for example, a CBOR array to a native `List` (or `ArrayList` in Java), or a CBOR integer to an `int` or `long` . To and from JSON: This class also doubles as a reader and writer of JavaScript Object Notation (JSON). The CBORObject.FromJSONString method converts JSON in text string form to a CBOR object, and the ToJSONString method converts a CBOR object to a JSON string. (Note that the conversion from CBOR to JSON is not always without loss and may make it impossible to recover the original object when converting the JSON back to CBOR. See the ToJSONString documentation.) Likewise, ToJSONBytes and FromJSONBytes work with JSON in the form of byte arrays rather than text strings. @@ -43,24 +43,44 @@ The DecodeFromBytes and Read methods can only read objects with a limited maximu The ReadJSON and FromJSONString methods currently have nesting depths of 1000. ### Member Summary +* [Abs()](#Abs) - Deprecated: Instead, convert this object to a number (with .AsNumber()), and use that number's .Abs() method. * [Add(object)](#Add_object) - Converts an object to a CBOR object and adds it to the end of this array. * [Add(object, object)](#Add_object_object) - Adds a new key and its value to this CBOR map, or adds the value if the key doesn't exist. * [Add(PeterO.Cbor.CBORObject)](#Add_PeterO_Cbor_CBORObject) - Adds a new object to the end of this array. +* [Addition(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#Addition_PeterO_Cbor_CBORObject_PeterO_Cbor_CBORObject) - Deprecated: Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Add() method. * [ApplyJSONPatch(PeterO.Cbor.CBORObject)](#ApplyJSONPatch_PeterO_Cbor_CBORObject) - Returns a copy of this object after applying the operations in a JSON patch, in the form of a CBOR object. * [AsBoolean()](#AsBoolean) - Returns false if this object is a CBOR false, null, or undefined value (whether or not the object has tags); otherwise, true. +* [AsByte()](#AsByte) - Deprecated: Instead, use .ToObject<byte>() in .NET or .ToObject(Byte.class) in Java. +* [AsDecimal()](#AsDecimal) - Deprecated: Instead, use .ToObject<decimal>(). * [AsDouble()](#AsDouble) - Converts this object to a 64-bit floating point number. * [AsDoubleBits()](#AsDoubleBits) - Converts this object to the bits of a 64-bit floating-point number if this CBOR object's type is FloatingPoint. * [AsDoubleValue()](#AsDoubleValue) - Converts this object to a 64-bit floating-point number if this CBOR object's type is FloatingPoint. +* [AsEDecimal()](#AsEDecimal) - Deprecated: Instead, use .ToObject<PeterO.Numbers.EDecimal>() in .NET or .ToObject(com.upokecenter.numbers.EDecimal.class) in Java. +* [AsEFloat()](#AsEFloat) - Deprecated: Instead, use .ToObject<PeterO.Numbers.EFloat>() in .NET or .ToObject(com.upokecenter.numbers.EFloat.class) in Java. +* [AsEInteger()](#AsEInteger) - Deprecated: Instead, use .ToObject<PeterO.Numbers.EInteger>() in .NET or .ToObject(com.upokecenter.numbers.EInteger.class) in Java. * [AsEIntegerValue()](#AsEIntegerValue) - Converts this object to an arbitrary-precision integer if this CBOR object's type is Integer. +* [AsERational()](#AsERational) - Deprecated: Instead, use .ToObject<PeterO.Numbers.ERational>() in .NET or .ToObject(com.upokecenter.numbers.ERational.class) in Java. +* [AsInt16()](#AsInt16) - Deprecated: Instead, use the following: (cbor.AsNumber().ToInt16Checked()), or .ToObject<short>() in .NET. * [AsInt32()](#AsInt32) - Converts this object to a 32-bit signed integer. * [AsInt32Value()](#AsInt32Value) - Converts this object to a 32-bit signed integer if this CBOR object's type is Integer. +* [AsInt64()](#AsInt64) - Deprecated: Instead, use the following: (cbor.AsNumber().ToInt64Checked()), or .ToObject<long>() in .NET. * [AsInt64Value()](#AsInt64Value) - Converts this object to a 64-bit signed integer if this CBOR object's type is Integer. * [AsNumber()](#AsNumber) - Converts this object to a CBOR number. +* [AsSByte()](#AsSByte) - Deprecated: Instead, use the following: (cbor.AsNumber().ToSByteChecked()), or .ToObject<sbyte>(). * [AsSingle()](#AsSingle) - Converts this object to a 32-bit floating point number. * [AsString()](#AsString) - Gets the value of this object as a text string. +* [AsUInt16()](#AsUInt16) - Deprecated: Instead, use the following: (cbor.AsNumber().ToUInt16Checked()), or .ToObject<ushort>(). +* [AsUInt32()](#AsUInt32) - Deprecated: Instead, use the following: (cbor.AsNumber().ToUInt32Checked()), or .ToObject<uint>(). +* [AsUInt64()](#AsUInt64) - Deprecated: Instead, use the following: (cbor.AsNumber().ToUInt64Checked()), or .ToObject<ulong>(). * [AtJSONPointer(string)](#AtJSONPointer_string) - Gets the CBOR object referred to by a JSON Pointer according to RFC6901. * [AtJSONPointer(string, PeterO.Cbor.CBORObject)](#AtJSONPointer_string_PeterO_Cbor_CBORObject) - Gets the CBOR object referred to by a JSON Pointer according to RFC6901, or a default value if the operation fails. * [CalcEncodedSize()](#CalcEncodedSize) - Calculates the number of bytes this CBOR object takes when serialized as a byte array using the EncodeToBytes() method. +* [CanFitInDouble()](#CanFitInDouble) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().CanFitInDouble()). +* [CanFitInInt32()](#CanFitInInt32) - Deprecated: Instead, use .CanValueFitInInt32(), if the application allows only CBOR integers, or (cbor.IsNumber &&cbor.AsNumber().CanFitInInt32()), if the application allows any CBOR object convertible to an integer. +* [CanFitInInt64()](#CanFitInInt64) - Deprecated: Instead, use CanValueFitInInt64(), if the application allows only CBOR integers, or (cbor.IsNumber &&cbor.AsNumber().CanFitInInt64()), if the application allows any CBOR object convertible to an integer. +* [CanFitInSingle()](#CanFitInSingle) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().CanFitInSingle()). +* [CanTruncatedIntFitInInt32()](#CanTruncatedIntFitInInt32) - Deprecated: Instead, use the following: (cbor.CanValueFitInInt32() if only integers of any tag are allowed, or (cbor.IsNumber && cbor.AsNumber().CanTruncatedIntFitInInt32()). +* [CanTruncatedIntFitInInt64()](#CanTruncatedIntFitInInt64) - Deprecated: Instead, use the following: (cbor.CanValueFitInInt64() if only integers of any tag are allowed, or (cbor.IsNumber && cbor.AsNumber().CanTruncatedIntFitInInt64()). * [CanValueFitInInt32()](#CanValueFitInInt32) - Returns whether this CBOR object stores an integer (CBORType. * [CanValueFitInInt64()](#CanValueFitInInt64) - Returns whether this CBOR object stores an integer (CBORType. * [Clear()](#Clear) - Removes all items from this CBOR array or all keys and values from this CBOR map. @@ -82,29 +102,14 @@ The ReadJSON and FromJSONString methods currently have nesting depths of 1000. * [DecodeObjectFromBytes<T>(byte[], PeterO.Cbor.CBORTypeMapper, PeterO.Cbor.PODOptions)](#DecodeObjectFromBytes_T_byte_PeterO_Cbor_CBORTypeMapper_PeterO_Cbor_PODOptions) - Generates an object of an arbitrary type from an array of CBOR-encoded bytes. * [DecodeSequenceFromBytes(byte[])](#DecodeSequenceFromBytes_byte) - Generates a sequence of CBOR objects from an array of CBOR-encoded bytes. * [DecodeSequenceFromBytes(byte[], PeterO.Cbor.CBOREncodeOptions)](#DecodeSequenceFromBytes_byte_PeterO_Cbor_CBOREncodeOptions) - Generates a sequence of CBOR objects from an array of CBOR-encoded bytes. +* [Divide(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#Divide_PeterO_Cbor_CBORObject_PeterO_Cbor_CBORObject) - Deprecated: Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Divide() method. * [EncodeToBytes()](#EncodeToBytes) - Writes the binary representation of this CBOR object and returns a byte array of that representation. * [EncodeToBytes(PeterO.Cbor.CBOREncodeOptions)](#EncodeToBytes_PeterO_Cbor_CBOREncodeOptions) - Writes the binary representation of this CBOR object and returns a byte array of that representation, using the specified options for encoding the object to CBOR format. * [Entries](#Entries) - Gets a collection of the key/value pairs stored in this CBOR object, if it's a map. * [Equals(object)](#Equals_object) - Determines whether this object and another object are equal and have the same type. * [Equals(PeterO.Cbor.CBORObject)](#Equals_PeterO_Cbor_CBORObject) - Compares the equality of two CBOR objects. * [public static readonly PeterO.Cbor.CBORObject False;](#False) - Represents the value false. -* [FromBool(bool)](#FromBool_bool) - Returns the CBOR true value or false value, depending on "value". -* [FromByte(byte)](#FromByte_byte) - Generates a CBOR object from a byte (0 to 255). -* [FromByteArray(byte[])](#FromByteArray_byte) - Generates a CBOR object from an array of 8-bit bytes; the byte array is copied to a new byte array in this process. -* [FromCBORArray(PeterO.Cbor.CBORObject[])](#FromCBORArray_PeterO_Cbor_CBORObject) - Generates a CBOR object from an array of CBOR objects. -* [FromCBORObjectAndTag(PeterO.Cbor.CBORObject, int)](#FromCBORObjectAndTag_PeterO_Cbor_CBORObject_int) - Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). -* [FromCBORObjectAndTag(PeterO.Cbor.CBORObject, PeterO.Numbers.EInteger)](#FromCBORObjectAndTag_PeterO_Cbor_CBORObject_PeterO_Numbers_EInteger) - Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). -* [FromCBORObjectAndTag(PeterO.Cbor.CBORObject, ulong)](#FromCBORObjectAndTag_PeterO_Cbor_CBORObject_ulong) - Generates a CBOR object from an arbitrary object and gives the resulting object a tag. -* [FromDecimal(decimal)](#FromDecimal_decimal) - Converts a. -* [FromDouble(double)](#FromDouble_double) - Generates a CBOR object from a 64-bit floating-point number. -* [FromEDecimal(PeterO.Numbers.EDecimal)](#FromEDecimal_PeterO_Numbers_EDecimal) - Generates a CBOR object from a decimal number. -* [FromEFloat(PeterO.Numbers.EFloat)](#FromEFloat_PeterO_Numbers_EFloat) - Generates a CBOR object from an arbitrary-precision binary floating-point number. -* [FromEInteger(PeterO.Numbers.EInteger)](#FromEInteger_PeterO_Numbers_EInteger) - Generates a CBOR object from an arbitrary-precision integer. -* [FromERational(PeterO.Numbers.ERational)](#FromERational_PeterO_Numbers_ERational) - Generates a CBOR object from an arbitrary-precision rational number. * [FromFloatingPointBits(long, int)](#FromFloatingPointBits_long_int) - Generates a CBOR object from a floating-point number represented by its bits. -* [FromInt16(short)](#FromInt16_short) - Generates a CBOR object from a 16-bit signed integer. -* [FromInt32(int)](#FromInt32_int) - Generates a CBOR object from a 32-bit signed integer. -* [FromInt64(long)](#FromInt64_long) - Generates a CBOR object from a 64-bit signed integer. * [FromJSONBytes(byte[])](#FromJSONBytes_byte) - Generates a CBOR object from a byte array in JavaScript Object Notation (JSON) format. * [FromJSONBytes(byte[], int, int)](#FromJSONBytes_byte_int_int) - Generates a CBOR object from a byte array in JavaScript Object Notation (JSON) format. * [FromJSONBytes(byte[], int, int, PeterO.Cbor.JSONOptions)](#FromJSONBytes_byte_int_int_PeterO_Cbor_JSONOptions) - Generates a CBOR object from a byte array in JavaScript Object Notation (JSON) format, using the specified options to control the decoding process. @@ -114,44 +119,38 @@ The ReadJSON and FromJSONString methods currently have nesting depths of 1000. * [FromJSONString(string)](#FromJSONString_string) - Generates a CBOR object from a text string in JavaScript Object Notation (JSON) format. * [FromJSONString(string, int, int)](#FromJSONString_string_int_int) - Generates a CBOR object from a text string in JavaScript Object Notation (JSON) format. * [FromJSONString(string, int, int, PeterO.Cbor.JSONOptions)](#FromJSONString_string_int_int_PeterO_Cbor_JSONOptions) - Generates a CBOR object from a text string in JavaScript Object Notation (JSON) format, using the specified options to control the decoding process. +* [FromJSONString(string, PeterO.Cbor.CBOREncodeOptions)](#FromJSONString_string_PeterO_Cbor_CBOREncodeOptions) - Deprecated: Instead, use .FromJSONString(str, new JSONOptions("allowduplicatekeys=true")) or .FromJSONString(str, new JSONOptions("allowduplicatekeys=false")), as appropriate. * [FromJSONString(string, PeterO.Cbor.JSONOptions)](#FromJSONString_string_PeterO_Cbor_JSONOptions) - Generates a CBOR object from a text string in JavaScript Object Notation (JSON) format, using the specified options to control the decoding process. -* [FromObject(bool)](#FromObject_bool) - Deprecated: Use FromBool instead. -* [FromObject(byte[])](#FromObject_byte) - Deprecated: Use FromByte instead. Deprecated: Use FromByteArray instead. -* [FromObject(decimal)](#FromObject_decimal) - Deprecated: Use FromDecimal instead -* [FromObject(double)](#FromObject_double) - Deprecated: Use FromDouble instead. -* [FromObject(float)](#FromObject_float) - Deprecated: Use FromFloat instead. -* [FromObject(int[])](#FromObject_int) - Deprecated: Use FromInt instead. Generates a CBOR object from an array of 32-bit integers. -* [FromObject(long[])](#FromObject_long) - Deprecated: Use FromInt64 instead. Generates a CBOR object from an array of 64-bit integers. +* [FromObject(bool)](#FromObject_bool) - Returns the CBOR true value or false value, depending on "value". +* [FromObject(byte[])](#FromObject_byte) - Generates a CBOR object from a byte (0 to 255). Generates a CBOR object from an array of 8-bit bytes; the byte array is copied to a new byte array in this process. +* [FromObject(decimal)](#FromObject_decimal) - Converts a. +* [FromObject(double)](#FromObject_double) - Generates a CBOR object from a 64-bit floating-point number. +* [FromObject(float)](#FromObject_float) - Generates a CBOR object from a 32-bit floating-point number. +* [FromObject(int[])](#FromObject_int) - Generates a CBOR object from a 32-bit signed integer. Generates a CBOR object from an array of 32-bit integers. +* [FromObject(long[])](#FromObject_long) - Generates a CBOR object from a 64-bit signed integer. Generates a CBOR object from an array of 64-bit integers. * [FromObject(object)](#FromObject_object) - Generates a CBORObject from an arbitrary object. * [FromObject(object, PeterO.Cbor.CBORTypeMapper)](#FromObject_object_PeterO_Cbor_CBORTypeMapper) - Generates a CBORObject from an arbitrary object. * [FromObject(object, PeterO.Cbor.CBORTypeMapper, PeterO.Cbor.PODOptions)](#FromObject_object_PeterO_Cbor_CBORTypeMapper_PeterO_Cbor_PODOptions) - Generates a CBORObject from an arbitrary object, using the given options to control how certain objects are converted to CBOR objects. * [FromObject(object, PeterO.Cbor.PODOptions)](#FromObject_object_PeterO_Cbor_PODOptions) - Generates a CBORObject from an arbitrary object. -* [FromObject(PeterO.Cbor.CBORObject[])](#FromObject_PeterO_Cbor_CBORObject) - Deprecated: Don't use a function and use Nullable Reference Types to guard against nulls. Deprecated: Use FromCBORArray instead. -* [FromObject(PeterO.Numbers.EDecimal)](#FromObject_PeterO_Numbers_EDecimal) - Deprecated: Use FromEDecimal instead. -* [FromObject(PeterO.Numbers.EFloat)](#FromObject_PeterO_Numbers_EFloat) - Deprecated: Use FromEFloat instead. -* [FromObject(PeterO.Numbers.EInteger)](#FromObject_PeterO_Numbers_EInteger) - Deprecated: Use FromEInteger instead. -* [FromObject(PeterO.Numbers.ERational)](#FromObject_PeterO_Numbers_ERational) - Deprecated: Use FromERational instead. -* [FromObject(sbyte)](#FromObject_sbyte) - Deprecated: Use FromSbyte instead -* [FromObject(short)](#FromObject_short) - Deprecated: Use FromInt16 instead. -* [FromObject(string)](#FromObject_string) - Deprecated: Use FromString instead. -* [FromObject(uint)](#FromObject_uint) - Deprecated: Use FromUInt instead -* [FromObject(ulong)](#FromObject_ulong) - Deprecated: Use FromUInt64 instead -* [FromObject(ushort)](#FromObject_ushort) - Deprecated: Use FromUShort instead -* [FromObjectAndTag(object, int)](#FromObjectAndTag_object_int) - Deprecated: Use FromCBORObjectAndTag instead. -* [FromObjectAndTag(object, PeterO.Numbers.EInteger)](#FromObjectAndTag_object_PeterO_Numbers_EInteger) - Deprecated: Use FromCBORObjectAndTag instead. -* [FromSbyte(sbyte)](#FromSbyte_sbyte) - Converts a signed 8-bit integer to a CBOR object. +* [FromObject(PeterO.Cbor.CBORObject[])](#FromObject_PeterO_Cbor_CBORObject) - Generates a CBOR object from a CBOR object. Generates a CBOR object from an array of CBOR objects. +* [FromObject(PeterO.Numbers.EDecimal)](#FromObject_PeterO_Numbers_EDecimal) - Generates a CBOR object from a decimal number. +* [FromObject(PeterO.Numbers.EFloat)](#FromObject_PeterO_Numbers_EFloat) - Generates a CBOR object from an arbitrary-precision binary floating-point number. +* [FromObject(PeterO.Numbers.EInteger)](#FromObject_PeterO_Numbers_EInteger) - Generates a CBOR object from an arbitrary-precision integer. +* [FromObject(PeterO.Numbers.ERational)](#FromObject_PeterO_Numbers_ERational) - Generates a CBOR object from an arbitrary-precision rational number. +* [FromObject(sbyte)](#FromObject_sbyte) - Converts a signed 8-bit integer to a CBOR object. +* [FromObject(short)](#FromObject_short) - Generates a CBOR object from a 16-bit signed integer. +* [FromObject(string)](#FromObject_string) - Generates a CBOR object from a text string. +* [FromObject(uint)](#FromObject_uint) - Converts a 32-bit unsigned integer to a CBOR object. +* [FromObject(ulong)](#FromObject_ulong) - Converts a 64-bit unsigned integer to a CBOR object. +* [FromObject(ushort)](#FromObject_ushort) - Converts a 16-bit unsigned integer to a CBOR object. +* [FromObjectAndTag(object, int)](#FromObjectAndTag_object_int) - Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). +* [FromObjectAndTag(object, PeterO.Numbers.EInteger)](#FromObjectAndTag_object_PeterO_Numbers_EInteger) - Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). +* [FromObjectAndTag(object, ulong)](#FromObjectAndTag_object_ulong) - Generates a CBOR object from an arbitrary object and gives the resulting object a tag. * [FromSimpleValue(int)](#FromSimpleValue_int) - Creates a CBOR object from a simple value number. -* [FromSingle(float)](#FromSingle_float) - Generates a CBOR object from a 32-bit floating-point number. -* [FromString(string)](#FromString_string) - Generates a CBOR object from a text string. -* [FromUInt(uint)](#FromUInt_uint) - Converts a 32-bit unsigned integer to a CBOR object. -* [FromUInt64(ulong)](#FromUInt64_ulong) - Converts a 64-bit unsigned integer to a CBOR object. -* [FromUShort(ushort)](#FromUShort_ushort) - Converts a 16-bit unsigned integer to a CBOR object. * [GetAllTags()](#GetAllTags) - Gets a list of all tags, from outermost to innermost. * [GetByteString()](#GetByteString) - Gets the backing byte array used in this CBOR object, if this object is a byte string, without copying the data to a new byte array. * [GetHashCode()](#GetHashCode) - Calculates the hash code of this object. -* [GetOrDefault(int, PeterO.Cbor.CBORObject)](#GetOrDefault_int_PeterO_Cbor_CBORObject) - Gets the value of a CBOR object by integer index in this array, or a default value if that value is not found. -* [GetOrDefault(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#GetOrDefault_PeterO_Cbor_CBORObject_PeterO_Cbor_CBORObject) - Gets the value of a CBOR object by integer index in this array or by CBOR object key in this map, or a default value if that value is not found. -* [GetOrDefault(string, PeterO.Cbor.CBORObject)](#GetOrDefault_string_PeterO_Cbor_CBORObject) - Gets the value of a CBOR object by string key in a map, or a default value if that value is not found. +* [GetOrDefault(object, PeterO.Cbor.CBORObject)](#GetOrDefault_object_PeterO_Cbor_CBORObject) - Gets the value of a CBOR object by integer index in this array or by CBOR object key in this map, or a default value if that value is not found. * [HasMostInnerTag(int)](#HasMostInnerTag_int) - Returns whether this object has an innermost tag and that tag is of the given number. * [HasMostInnerTag(PeterO.Numbers.EInteger)](#HasMostInnerTag_PeterO_Numbers_EInteger) - Returns whether this object has an innermost tag and that tag is of the given number, expressed as an arbitrary-precision number. * [HasMostOuterTag(int)](#HasMostOuterTag_int) - Returns whether this object has an outermost tag and that tag is of the given number. @@ -161,43 +160,59 @@ The ReadJSON and FromJSONString methods currently have nesting depths of 1000. * [HasOneTag(PeterO.Numbers.EInteger)](#HasOneTag_PeterO_Numbers_EInteger) - Returns whether this object has only one tag and that tag is the given number, expressed as an arbitrary-precision integer. * [HasTag(int)](#HasTag_int) - Returns whether this object has a tag of the given number. * [HasTag(PeterO.Numbers.EInteger)](#HasTag_PeterO_Numbers_EInteger) - Returns whether this object has a tag of the given number. -* [Insert(int, object)](#Insert_int_object) - Deprecated: Use the CBORObject overload instead. -* [Insert(int, PeterO.Cbor.CBORObject)](#Insert_int_PeterO_Cbor_CBORObject) - Inserts a CBORObject at the specified position in this CBOR array. +* [Insert(int, object)](#Insert_int_object) - Inserts an object at the specified position in this CBOR array. * [IsFalse](#IsFalse) - Gets a value indicating whether this value is a CBOR false value, whether tagged or not. +* [IsFinite](#IsFinite) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsFinite()). +* [IsInfinity()](#IsInfinity) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsInfinity()). +* [IsIntegral](#IsIntegral) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsInteger()). +* [IsNaN()](#IsNaN) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsNaN()). +* [IsNegative](#IsNegative) - Deprecated: Instead, use (cbor.IsNumber() && cbor.AsNumber().IsNegative()). +* [IsNegativeInfinity()](#IsNegativeInfinity) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsNegativeInfinity()). * [IsNull](#IsNull) - Gets a value indicating whether this CBOR object is a CBOR null value, whether tagged or not. * [IsNumber](#IsNumber) - Gets a value indicating whether this CBOR object stores a number (including infinity or a not-a-number or NaN value). +* [IsPositiveInfinity()](#IsPositiveInfinity) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsPositiveInfinity()). * [IsTagged](#IsTagged) - Gets a value indicating whether this data item has at least one tag. * [IsTrue](#IsTrue) - Gets a value indicating whether this value is a CBOR true value, whether tagged or not. * [IsUndefined](#IsUndefined) - Gets a value indicating whether this value is a CBOR undefined value, whether tagged or not. +* [IsZero](#IsZero) - Deprecated: Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsZero()). * [Keys](#Keys) - Gets a collection of the keys of this CBOR object. * [MostInnerTag](#MostInnerTag) - Gets the last defined tag for this CBOR data item, or -1 if the item is untagged. * [MostOuterTag](#MostOuterTag) - Gets the outermost tag for this CBOR data item, or -1 if the item is untagged. +* [Multiply(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#Multiply_PeterO_Cbor_CBORObject_PeterO_Cbor_CBORObject) - Deprecated: Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Multiply() method. * [public static readonly PeterO.Cbor.CBORObject NaN;](#NaN) - A not-a-number value. +* [Negate()](#Negate) - Deprecated: Instead, convert this object to a number (with .AsNumber()), and use that number's .Negate() method. * [public static readonly PeterO.Cbor.CBORObject NegativeInfinity;](#NegativeInfinity) - The value negative infinity. * [NewArray()](#NewArray) - Creates a new empty CBOR array. * [NewMap()](#NewMap) - Creates a new empty CBOR map that stores its keys in an undefined order. * [NewOrderedMap()](#NewOrderedMap) - Creates a new empty CBOR map that ensures that keys are stored in the order in which they are first inserted. * [public static readonly PeterO.Cbor.CBORObject Null;](#Null) - Represents the value null. +* [PeterO.Cbor.CBORObject operator +(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_Addition) - Deprecated: May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. +* [PeterO.Cbor.CBORObject operator /(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_Division) - Deprecated: May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. * [bool operator >(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_GreaterThan) - Returns whether one object's value is greater than another's. * [bool operator >=(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_GreaterThanOrEqual) - Returns whether one object's value is at least another's. * [bool operator <(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_LessThan) - Returns whether one object's value is less than another's. * [bool operator <=(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_LessThanOrEqual) - Returns whether one object's value is up to another's. +* [PeterO.Cbor.CBORObject operator %(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_Modulus) - Deprecated: May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. +* [PeterO.Cbor.CBORObject operator *(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_Multiply) - Deprecated: May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. +* [PeterO.Cbor.CBORObject operator -(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#op_Subtraction) - Deprecated: May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. * [public static readonly PeterO.Cbor.CBORObject PositiveInfinity;](#PositiveInfinity) - The value positive infinity. * [Read(System.IO.Stream)](#Read_System_IO_Stream) - Reads an object in CBOR format from a data stream. * [Read(System.IO.Stream, PeterO.Cbor.CBOREncodeOptions)](#Read_System_IO_Stream_PeterO_Cbor_CBOREncodeOptions) - Reads an object in CBOR format from a data stream, using the specified options to control the decoding process. * [ReadJSON(System.IO.Stream)](#ReadJSON_System_IO_Stream) - Generates a CBOR object from a data stream in JavaScript Object Notation (JSON) format. +* [ReadJSON(System.IO.Stream, PeterO.Cbor.CBOREncodeOptions)](#ReadJSON_System_IO_Stream_PeterO_Cbor_CBOREncodeOptions) - Deprecated: Instead, use .ReadJSON(stream, new JSONOptions("allowduplicatekeys=true")) or .ReadJSON(stream, new JSONOptions("allowduplicatekeys=false")), as appropriate. * [ReadJSON(System.IO.Stream, PeterO.Cbor.JSONOptions)](#ReadJSON_System_IO_Stream_PeterO_Cbor_JSONOptions) - Generates a CBOR object from a data stream in JavaScript Object Notation (JSON) format, using the specified options to control the decoding process. * [ReadJSONSequence(System.IO.Stream)](#ReadJSONSequence_System_IO_Stream) - Generates a list of CBOR objects from a data stream in JavaScript Object Notation (JSON) text sequence format (RFC 7464). * [ReadJSONSequence(System.IO.Stream, PeterO.Cbor.JSONOptions)](#ReadJSONSequence_System_IO_Stream_PeterO_Cbor_JSONOptions) - Generates a list of CBOR objects from a data stream in JavaScript Object Notation (JSON) text sequence format (RFC 7464). * [ReadSequence(System.IO.Stream)](#ReadSequence_System_IO_Stream) - Reads a sequence of objects in CBOR format from a data stream. * [ReadSequence(System.IO.Stream, PeterO.Cbor.CBOREncodeOptions)](#ReadSequence_System_IO_Stream_PeterO_Cbor_CBOREncodeOptions) - Reads a sequence of objects in CBOR format from a data stream. +* [Remainder(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#Remainder_PeterO_Cbor_CBORObject_PeterO_Cbor_CBORObject) - Deprecated: Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Remainder() method. * [Remove(object)](#Remove_object) - If this object is an array, removes the first instance of the specified item (once converted to a CBOR object) from the array. * [Remove(PeterO.Cbor.CBORObject)](#Remove_PeterO_Cbor_CBORObject) - If this object is an array, removes the first instance of the specified item from the array. * [RemoveAt(int)](#RemoveAt_int) - Removes the item at the given index of this CBOR array. -* [Set(int, PeterO.Cbor.CBORObject)](#Set_int_PeterO_Cbor_CBORObject) - Sets the value of a CBORObject of type Array at the given index to the given value. -* [Set(object, object)](#Set_object_object) - Deprecated: Use the CBORObject overload instead. -* [Set(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#Set_PeterO_Cbor_CBORObject_PeterO_Cbor_CBORObject) - Maps an object to a key in this CBOR map, or adds the value if the key doesn't exist. +* [Set(object, object)](#Set_object_object) - Maps an object to a key in this CBOR map, or adds the value if the key doesn't exist. +* [Sign](#Sign) - Deprecated: Instead, convert this object to a number with .AsNumber(), and use the Sign property in .NET or the signum method in Java. Either will treat not-a-number (NaN) values differently than here. * [SimpleValue](#SimpleValue) - Gets the simple value ID of this CBOR object, or -1 if the object is not a simple value. +* [Subtract(PeterO.Cbor.CBORObject, PeterO.Cbor.CBORObject)](#Subtract_PeterO_Cbor_CBORObject_PeterO_Cbor_CBORObject) - Deprecated: Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Subtract() method. * [TagCount](#TagCount) - Gets the number of tags this object has. * [this[int]](#this_int) - Gets the value of a CBOR object by integer index in this array or by integer key in this map. * [this[PeterO.Cbor.CBORObject]](#this_PeterO_Cbor_CBORObject) - Gets the value of a CBOR object by integer index in this array or by CBOR object key in this map. @@ -354,6 +369,45 @@ Gets a value indicating whether this value is a CBOR false value, whether tagged `true` if this value is a CBOR false value; otherwise, `false` . + +### IsFinite + + public bool IsFinite { get; } + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsFinite()). + +Gets a value indicating whether this CBOR object represents a finite number. + +Returns: + + `true` if this CBOR object represents a finite number; otherwise, `false` . + + +### IsIntegral + + public bool IsIntegral { get; } + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsInteger()). + +Gets a value indicating whether this object represents an integer number, that is, a number without a fractional part. Infinity and not-a-number are not considered integers. + +Returns: + + `true` if this object represents an integer number, that is, a number without a fractional part; otherwise, `false` . + + +### IsNegative + + public bool IsNegative { get; } + +Deprecated. Instead, use (cbor.IsNumber() && cbor.AsNumber().IsNegative()). + +Gets a value indicating whether this object is a negative number. + +Returns: + + `true` if this object is a negative number; otherwise, `false` . + ### IsNull @@ -409,6 +463,19 @@ Gets a value indicating whether this value is a CBOR undefined value, whether ta `true` if this value is a CBOR undefined value; otherwise, `false` . + +### IsZero + + public bool IsZero { get; } + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsZero()). + +Gets a value indicating whether this object's value equals 0. + +Returns: + + `true` if this object's value equals 0; otherwise, `false` . + ### Item @@ -441,7 +508,7 @@ Gets a collection of the keys of this CBOR object. In general, the order in whic Returns: -A read-only collection of the keys of this CBOR object. To avoid potential problems, the calling code should not modify the CBOR map while iterating over the returned collection. +A collection of the keys of this CBOR object. To avoid potential problems, the calling code should not modify the CBOR map or the returned collection while iterating over the returned collection. Exceptions: @@ -470,6 +537,24 @@ Gets the outermost tag for this CBOR data item, or -1 if the item is untagged. The outermost tag for this CBOR data item, or -1 if the item is untagged. + +### Sign + + public int Sign { get; } + +Deprecated. Instead, convert this object to a number with .AsNumber(), and use the Sign property in .NET or the signum method in Java. Either will treat not-a-number (NaN) values differently than here. + +Gets this value's sign: -1 if negative; 1 if positive; 0 if zero. Throws an exception if this is a not-a-number value. + +Returns: + +This value's sign: -1 if negative; 1 if positive; 0 if zero. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number, or this object is a not-a-number (NaN) value. + ### SimpleValue @@ -512,13 +597,31 @@ Gets a collection of the values of this CBOR object, if it's a map or an array. Returns: -A read-only collection of the values of this CBOR map or array. To avoid potential problems, the calling code should not modify the CBOR map or array while iterating over the returned collection. +A collection of the values of this CBOR map or array. To avoid potential problems, the calling code should not modify the CBOR map or array or the returned collection while iterating over the returned collection. Exceptions: * System.InvalidOperationException: This object is not a map or an array. + +### Abs + + public PeterO.Cbor.CBORObject Abs(); + +Deprecated. Instead, convert this object to a number (with .AsNumber()), and use that number's .Abs() method. + +Gets this object's absolute value. + +Return Value: + +This object's absolute without its negative sign. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + ### Add @@ -528,7 +631,7 @@ This object is not a map or an array. Adds a new key and its value to this CBOR map, or adds the value if the key doesn't exist. -NOTE: This method can't be used to add a tag to an existing CBOR object. To create a CBOR object with a given tag, call the `CBORObject.FromCBORObjectAndTag` method and pass the CBOR object and the desired tag number to that method. +NOTE: This method can't be used to add a tag to an existing CBOR object. To create a CBOR object with a given tag, call the `CBORObject.FromObjectAndTag` method and pass the CBOR object and the desired tag number to that method. Parameters: @@ -562,12 +665,12 @@ The parameter key Converts an object to a CBOR object and adds it to the end of this array. -NOTE: This method can't be used to add a tag to an existing CBOR object. To create a CBOR object with a given tag, call the `CBORObject.FromCBORObjectAndTag` method and pass the CBOR object and the desired tag number to that method. +NOTE: This method can't be used to add a tag to an existing CBOR object. To create a CBOR object with a given tag, call the `CBORObject.FromObjectAndTag` method and pass the CBOR object and the desired tag number to that method. The following example creates a CBOR array and adds several CBOR objects, one of which has a custom CBOR tag, to that array. Note the chaining behavior made possible by this method. CBORObject obj = CBORObject.NewArray() .Add(CBORObject.False) .Add(5) - .Add("text string") .Add(CBORObject.FromCBORObjectAndTag(9999, 1)); + .Add("text string") .Add(CBORObject.FromObjectAndTag(9999, 1)); . @@ -596,13 +699,13 @@ The type of obj Adds a new object to the end of this array. (Used to throw ArgumentNullException on a null reference, but now converts the null reference to CBORObject.Null, for convenience with the Object overload of this method). -NOTE: This method can't be used to add a tag to an existing CBOR object. To create a CBOR object with a given tag, call the `CBORObject.FromCBORObjectAndTag` method and pass the CBOR object and the desired tag number to that method. +NOTE: This method can't be used to add a tag to an existing CBOR object. To create a CBOR object with a given tag, call the `CBORObject.FromObjectAndTag` method and pass the CBOR object and the desired tag number to that method. The following example creates a CBOR array and adds several CBOR objects, one of which has a custom CBOR tag, to that array. Note the chaining behavior made possible by this method. CBORObject obj = CBORObject.NewArray() .Add(CBORObject.False) .Add(CBORObject.FromObject(5)) .Add(CBORObject.FromObject("text - string")) .Add(CBORObject.FromCBORObjectAndTag(9999, 1)); + string")) .Add(CBORObject.FromObjectAndTag(9999, 1)); . @@ -620,6 +723,39 @@ This instance. * System.InvalidOperationException: This object is not an array. + +### Addition + + public static PeterO.Cbor.CBORObject Addition( + PeterO.Cbor.CBORObject first, + PeterO.Cbor.CBORObject second); + +Deprecated. Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Add() method. + +Finds the sum of two CBOR numbers. + +Parameters: + + * first: The parameter first + is a CBOR object. + + * second: The parameter second + is a CBOR object. + +Return Value: + +A CBOR object. + +Exceptions: + + * System.ArgumentException: +Either or both operands are not numbers (as opposed to Not-a-Number, NaN). + + * System.ArgumentNullException: +The parameter first + or second + is null. + ### ApplyJSONPatch @@ -663,6 +799,48 @@ Returns false if this object is a CBOR false, null, or undefined value (whether False if this object is a CBOR false, null, or undefined value; otherwise, true. + +### AsByte + + public byte AsByte(); + +Deprecated. Instead, use .ToObject<byte>() in .NET or .ToObject(Byte.class) in Java. + +Converts this object to a byte (0 to 255). Floating point values are converted to integers by discarding their fractional parts. + +Return Value: + +The closest byte-sized integer to this object. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + + * System.OverflowException: +This object's value exceeds the range of a byte (would be less than 0 or greater than 255 when converted to an integer by discarding its fractional part). + + +### AsDecimal + + public decimal AsDecimal(); + +Deprecated. Instead, use .ToObject<decimal>(). + +Converts this object to a DotNet decimal. + +Return Value: + +The closest big integer to this object. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + + * System.OverflowException: +This object's value exceeds the range of a DotNet decimal. + ### AsDouble @@ -711,6 +889,63 @@ The 64-bit floating-point number stored by this object. * System.InvalidOperationException: This object's type is not `CBORType.FloatingPoint` . + +### AsEDecimal + + public PeterO.Numbers.EDecimal AsEDecimal(); + +Deprecated. Instead, use .ToObject<PeterO.Numbers.EDecimal>() in .NET or .ToObject(com.upokecenter.numbers.EDecimal.class) in Java. + +Converts this object to a decimal number. + +Return Value: + +A decimal number for this object's value. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for the purposes of this method, infinity and not-a-number values, but not `CBORObject.Null` , are considered numbers). + + +### AsEFloat + + public PeterO.Numbers.EFloat AsEFloat(); + +Deprecated. Instead, use .ToObject<PeterO.Numbers.EFloat>() in .NET or .ToObject(com.upokecenter.numbers.EFloat.class) in Java. + +Converts this object to an arbitrary-precision binary floating point number. See the ToObject overload taking a type for more information. + +Return Value: + +An arbitrary-precision binary floating-point number for this object's value. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for the purposes of this method, infinity and not-a-number values, but not `CBORObject.Null` , are considered numbers). + + +### AsEInteger + + public PeterO.Numbers.EInteger AsEInteger(); + +Deprecated. Instead, use .ToObject<PeterO.Numbers.EInteger>() in .NET or .ToObject(com.upokecenter.numbers.EInteger.class) in Java. + +Converts this object to an arbitrary-precision integer. See the ToObject overload taking a type for more information. + +Return Value: + +The closest arbitrary-precision integer to this object. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for the purposes of this method, infinity and not-a-number values, but not `CBORObject.Null` , are considered numbers). + + * System.OverflowException: +This object's value is infinity or not-a-number (NaN). + ### AsEIntegerValue @@ -727,6 +962,45 @@ The integer stored by this object. * System.InvalidOperationException: This object's type is not `CBORType.Integer` . + +### AsERational + + public PeterO.Numbers.ERational AsERational(); + +Deprecated. Instead, use .ToObject<PeterO.Numbers.ERational>() in .NET or .ToObject(com.upokecenter.numbers.ERational.class) in Java. + +Converts this object to a rational number. See the ToObject overload taking a type for more information. + +Return Value: + +A rational number for this object's value. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for the purposes of this method, infinity and not-a-number values, but not `CBORObject.Null` , are considered numbers). + + +### AsInt16 + + public short AsInt16(); + +Deprecated. Instead, use the following: (cbor.AsNumber().ToInt16Checked()), or .ToObject<short>() in .NET. + +Converts this object to a 16-bit signed integer. Floating point values are converted to integers by discarding their fractional parts. + +Return Value: + +The closest 16-bit signed integer to this object. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + + * System.OverflowException: +This object's value exceeds the range of a 16-bit signed integer. + ### AsInt32 @@ -784,6 +1058,37 @@ This object's type is not `CBORType.Integer` . * System.OverflowException: This object's value exceeds the range of a 32-bit signed integer. + +### AsInt64 + + public long AsInt64(); + +Deprecated. Instead, use the following: (cbor.AsNumber().ToInt64Checked()), or .ToObject<long>() in .NET. + +Converts this object to a 64-bit signed integer. Non-integer numbers are converted to integers by discarding their fractional parts. (NOTE: To determine whether this method call can succeed, call AsNumber().CanTruncatedIntFitInInt64 before calling this method. See the example.). + +The following example code (originally written in C# for the.NET Framework) shows a way to check whether a given CBOR object stores a 64-bit signed integer before getting its value. + + CBORObject obj = CBORObject.FromInt64(99999); + if (obj.IsIntegral && obj.AsNumber().CanFitInInt64()) { + /* Not an Int64; handle the error */ + Console.WriteLine("Not a 64-bit integer."); } else { + Console.WriteLine("The value is " + obj.AsInt64()); } + + . + +Return Value: + +The closest 64-bit signed integer to this object. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + + * System.OverflowException: +This object's value exceeds the range of a 64-bit signed integer. + ### AsInt64Value @@ -829,6 +1134,21 @@ The number represented by this object. * System.InvalidOperationException: This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + +### AsSByte + + public sbyte AsSByte(); + +Deprecated. Instead, use the following: (cbor.AsNumber().ToSByteChecked()), or .ToObject<sbyte>(). + +This API is not CLS-compliant. + +Converts this object to an 8-bit signed integer. + +Return Value: + +An 8-bit signed integer. + ### AsSingle @@ -852,7 +1172,7 @@ This object does not represent a number (for this purpose, infinities and not-a- Gets the value of this object as a text string. -This method is not the "reverse" of the `FromString` method in the sense that FromString can take either a text string or `null` , but this method can accept only text strings. The `ToObject` method is closer to a "reverse" version to `FromString` than the `AsString` method: `ToObject(cbor)` in DotNet, or `ToObject(String.class)` in Java, will convert a CBOR object to a DotNet or Java String if it represents a text string, or to `null` if `IsNull` returns `true` for the CBOR object, and will fail in other cases. +This method is not the "reverse" of the `FromObject` method in the sense that FromObject can take either a text string or `null` , but this method can accept only text strings. The `ToObject` method is closer to a "reverse" version to `FromObject` than the `AsString` method: `ToObject(cbor)` in DotNet, or `ToObject(String.class)` in Java, will convert a CBOR object to a DotNet or Java String if it represents a text string, or to `null` if `IsNull` returns `true` for the CBOR object, and will fail in other cases. Return Value: @@ -864,6 +1184,75 @@ Gets this object's string. This object's type is not a text string (for the purposes of this method, infinity and not-a-number values, but not `CBORObject.Null` , are considered numbers). To check the CBOR object for null before conversion, use the following idiom (originally written in C# for the.NET version): `(cbor == null || cbor.IsNull) ? null : cbor.AsString()` . + +### AsUInt16 + + public ushort AsUInt16(); + +Deprecated. Instead, use the following: (cbor.AsNumber().ToUInt16Checked()), or .ToObject<ushort>(). + +This API is not CLS-compliant. + +Converts this object to a 16-bit unsigned integer after discarding any fractional part, if any, from its value. + +Return Value: + +A 16-bit unsigned integer. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + + * System.OverflowException: +This object's value, if converted to an integer by discarding its fractional part, is outside the range of a 16-bit unsigned integer. + + +### AsUInt32 + + public uint AsUInt32(); + +Deprecated. Instead, use the following: (cbor.AsNumber().ToUInt32Checked()), or .ToObject<uint>(). + +This API is not CLS-compliant. + +Converts this object to a 32-bit unsigned integer after discarding any fractional part, if any, from its value. + +Return Value: + +A 32-bit unsigned integer. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + + * System.OverflowException: +This object's value, if converted to an integer by discarding its fractional part, is outside the range of a 32-bit unsigned integer. + + +### AsUInt64 + + public ulong AsUInt64(); + +Deprecated. Instead, use the following: (cbor.AsNumber().ToUInt64Checked()), or .ToObject<ulong>(). + +This API is not CLS-compliant. + +Converts this object to a 64-bit unsigned integer after discarding any fractional part, if any, from its value. + +Return Value: + +A 64-bit unsigned integer. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). + + * System.OverflowException: +This object's value, if converted to an integer by discarding its fractional part, is outside the range of a 64-bit unsigned integer. + ### AtJSONPointer @@ -922,36 +1311,114 @@ The number of bytes this CBOR object takes when serialized as a byte array using * PeterO.Cbor.CBORException: The CBOR object has an extremely deep level of nesting, including if the CBOR object is or has an array or map that includes itself. - -### CanValueFitInInt32 + +### CanFitInDouble - public bool CanValueFitInInt32(); + public bool CanFitInDouble(); -Returns whether this CBOR object stores an integer (CBORType.Integer) within the range of a 32-bit signed integer. This method disregards the tags this object has, if any. +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().CanFitInDouble()). + +Returns whether this object's value can be converted to a 64-bit floating point number without its value being rounded to another numerical value. Return Value: - `true` if this CBOR object stores an integer (CBORType.Integer) whose value is at least -(2^31) and less than 2^31; otherwise, `false` . + `true` if this object's value can be converted to a 64-bit floating point number without its value being rounded to another numerical value, or if this is a not-a-number value, even if the value's diagnostic information can't fit in a 64-bit floating point number; otherwise, `false` . - -### CanValueFitInInt64 + +### CanFitInInt32 - public bool CanValueFitInInt64(); + public bool CanFitInInt32(); -Returns whether this CBOR object stores an integer (CBORType.Integer) within the range of a 64-bit signed integer. This method disregards the tags this object has, if any. +Deprecated. Instead, use .CanValueFitInInt32(), if the application allows only CBOR integers, or (cbor.IsNumber &&cbor.AsNumber().CanFitInInt32()), if the application allows any CBOR object convertible to an integer. + +Returns whether this object's numerical value is an integer, is -(2^31) or greater, and is less than 2^31. Return Value: - `true` if this CBOR object stores an integer (CBORType.Integer) whose value is at least -(2^63) and less than 2^63; otherwise, `false` . + `true` if this object's numerical value is an integer, is -(2^31) or greater, and is less than 2^31; otherwise, `false` . - -### Clear + +### CanFitInInt64 - public void Clear(); + public bool CanFitInInt64(); -Removes all items from this CBOR array or all keys and values from this CBOR map. +Deprecated. Instead, use CanValueFitInInt64(), if the application allows only CBOR integers, or (cbor.IsNumber &&cbor.AsNumber().CanFitInInt64()), if the application allows any CBOR object convertible to an integer. -Exceptions: +Returns whether this object's numerical value is an integer, is -(2^63) or greater, and is less than 2^63. + +Return Value: + + `true` if this object's numerical value is an integer, is -(2^63) or greater, and is less than 2^63; otherwise, `false` . + + +### CanFitInSingle + + public bool CanFitInSingle(); + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().CanFitInSingle()). + +Returns whether this object's value can be converted to a 32-bit floating point number without its value being rounded to another numerical value. + +Return Value: + + `true` if this object's value can be converted to a 32-bit floating point number without its value being rounded to another numerical value, or if this is a not-a-number value, even if the value's diagnostic information can' t fit in a 32-bit floating point number; otherwise, `false` . + + +### CanTruncatedIntFitInInt32 + + public bool CanTruncatedIntFitInInt32(); + +Deprecated. Instead, use the following: (cbor.CanValueFitInInt32() if only integers of any tag are allowed, or (cbor.IsNumber && cbor.AsNumber().CanTruncatedIntFitInInt32()). + +Returns whether this object's value, converted to an integer by discarding its fractional part, would be -(2^31) or greater, and less than 2^31. + +Return Value: + + `true` if this object's value, converted to an integer by discarding its fractional part, would be -(2^31) or greater, and less than 2^31; otherwise, `false` . + + +### CanTruncatedIntFitInInt64 + + public bool CanTruncatedIntFitInInt64(); + +Deprecated. Instead, use the following: (cbor.CanValueFitInInt64() if only integers of any tag are allowed, or (cbor.IsNumber && cbor.AsNumber().CanTruncatedIntFitInInt64()). + +Returns whether this object's value, converted to an integer by discarding its fractional part, would be -(2^63) or greater, and less than 2^63. + +Return Value: + + `true` if this object's value, converted to an integer by discarding its fractional part, would be -(2^63) or greater, and less than 2^63; otherwise, `false` . + + +### CanValueFitInInt32 + + public bool CanValueFitInInt32(); + +Returns whether this CBOR object stores an integer (CBORType.Integer) within the range of a 32-bit signed integer. This method disregards the tags this object has, if any. + +Return Value: + + `true` if this CBOR object stores an integer (CBORType.Integer) whose value is at least -(2^31) and less than 2^31; otherwise, `false` . + + +### CanValueFitInInt64 + + public bool CanValueFitInInt64(); + +Returns whether this CBOR object stores an integer (CBORType.Integer) within the range of a 64-bit signed integer. This method disregards the tags this object has, if any. + +Return Value: + + `true` if this CBOR object stores an integer (CBORType.Integer) whose value is at least -(2^63) and less than 2^63; otherwise, `false` . + + +### Clear + + public void Clear(); + +Removes all items from this CBOR array or all keys and values from this CBOR map. + +Exceptions: * System.InvalidOperationException: This object is not a CBOR array or CBOR map. @@ -1466,6 +1933,36 @@ The parameter data is null, or the parameter options is null. + +### Divide + + public static PeterO.Cbor.CBORObject Divide( + PeterO.Cbor.CBORObject first, + PeterO.Cbor.CBORObject second); + +Deprecated. Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Divide() method. + +Divides a CBORObject object by the value of a CBORObject object. + +Parameters: + + * first: The parameter first + is a CBOR object. + + * second: The parameter second + is a CBOR object. + +Return Value: + +The quotient of the two objects. + +Exceptions: + + * System.ArgumentNullException: +The parameter first + or second + is null. + ### EncodeToBytes @@ -1531,366 +2028,32 @@ Compares the equality of two CBOR objects. Not-a-number values can be considered Return Value: - `true` if the objects are equal; otherwise, `false` . In this method, two objects are not equal if they don't have the same type or if one is null and the other isn't. - - -### FromBool - - public static PeterO.Cbor.CBORObject FromBool( - bool value); - -Returns the CBOR true value or false value, depending on "value". - -Parameters: - - * value: Either `true` or `false` . - -Return Value: - -CBORObject.True if value is true; otherwise CBORObject.False. - - -### FromByte - - public static PeterO.Cbor.CBORObject FromByte( - byte value); - -Generates a CBOR object from a byte (0 to 255). - -Parameters: - - * value: The parameter value - is a byte (from 0 to 255). - -Return Value: - -A CBOR object generated from the given integer. - - -### FromByteArray - - public static PeterO.Cbor.CBORObject FromByteArray( - byte[] bytes); - -Generates a CBOR object from an array of 8-bit bytes; the byte array is copied to a new byte array in this process. (This method can't be used to decode CBOR data from a byte array; for that, use the DecodeFromBytes method instead.). - -Parameters: - - * bytes: An array of 8-bit bytes; can be null. - -Return Value: - -A CBOR object where each element of the given byte array is copied to a new array, or CBORObject.Null if the value is null. - - -### FromCBORArray - - public static PeterO.Cbor.CBORObject FromCBORArray( - PeterO.Cbor.CBORObject[] array); - -Generates a CBOR object from an array of CBOR objects. - -Parameters: - - * array: An array of CBOR objects. - -Return Value: - -A CBOR object where each element of the given array is copied to a new array, or CBORObject.Null if the value is null. - - -### FromCBORObjectAndTag - - public static PeterO.Cbor.CBORObject FromCBORObjectAndTag( - PeterO.Cbor.CBORObject cborObj, - int smallTag); - -Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). - -Parameters: - - * cborObj: The parameter cborObj - is a CBORObject. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. - -. - - * smallTag: A 32-bit integer that specifies a tag number. The tag number 55799 can be used to mark a "self-described CBOR" object. This document does not attempt to list all CBOR tags and their meanings. An up-to-date list can be found at the CBOR Tags registry maintained by the Internet Assigned Numbers Authority ( iana.org/assignments/cbor-tags ). - -Return Value: - -A CBOR object where the object cborObj - is given the tag smallTag -. If "valueOb" is null, returns a version of CBORObject.Null with the given tag. - -Exceptions: - - * System.ArgumentException: -The parameter smallTag - is less than 0. - - -### FromCBORObjectAndTag - - public static PeterO.Cbor.CBORObject FromCBORObjectAndTag( - PeterO.Cbor.CBORObject cborObj, - PeterO.Numbers.EInteger bigintTag); - -Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). - -Parameters: - - * cborObj: The parameter cborObj - is a CBORObject. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. - -. - - * bigintTag: Tag number. The tag number 55799 can be used to mark a "self-described CBOR" object. This document does not attempt to list all CBOR tags and their meanings. An up-to-date list can be found at the CBOR Tags registry maintained by the Internet Assigned Numbers Authority( iana.org/assignments/cbor-tags ). - -Return Value: - -A CBOR object where the object cborObj - is given the tag bigintTag -. - -Exceptions: - - * System.ArgumentException: -The parameter bigintTag - is less than 0 or greater than 2^64-1. - - * System.ArgumentNullException: -The parameter bigintTag - is null. - - -### FromCBORObjectAndTag - - public static PeterO.Cbor.CBORObject FromCBORObjectAndTag( - PeterO.Cbor.CBORObject o, - ulong tag); - -This API is not CLS-compliant. - -Generates a CBOR object from an arbitrary object and gives the resulting object a tag. - -Parameters: - - * o: The parameter o - is an arbitrary CBORObject. - - * tag: A 64-bit integer that specifies a tag number. The tag number 55799 can be used to mark a "self-described CBOR" object. This document does not attempt to list all CBOR tags and their meanings. An up-to-date list can be found at the CBOR Tags registry maintained by the Internet Assigned Numbers Authority( iana.org/assignments/cbor-tags ). - -Return Value: - -A CBOR object where the object o - is given the tag tag -. If "valueOb" is null, returns a version of CBORObject.Null with the given tag. - - -### FromDecimal - - public static PeterO.Cbor.CBORObject FromDecimal( - decimal value); - -Converts a.NET decimal to a CBOR object. - -Parameters: - - * value: The parameter value - is a Decimal object. - -Return Value: - -A CBORObject object with the same value as the.NET decimal. - - -### FromDouble - - public static PeterO.Cbor.CBORObject FromDouble( - double value); - -Generates a CBOR object from a 64-bit floating-point number. The input value can be a not-a-number (NaN) value (such as `Double.NaN` ); however, NaN values have multiple forms that are equivalent for many applications' purposes, and `Double.NaN` is only one of these equivalent forms. In fact, `CBORObject.FromDouble(Double.NaN)` could produce a CBOR-encoded object that differs between DotNet and Java, because `Double.NaN` may have a different form in DotNet and Java (for example, the NaN value's sign may be negative in DotNet, but positive in Java). - -Parameters: - - * value: The parameter value - is a 64-bit floating-point number. - -Return Value: - -A CBOR object generated from the given number. - - -### FromEDecimal - - public static PeterO.Cbor.CBORObject FromEDecimal( - PeterO.Numbers.EDecimal bigValue); - -Generates a CBOR object from a decimal number. The CBOR object is generated as follows (this is a change in version 4.0): - - * If the number is null, returns CBORObject.Null. - - * Otherwise, if the number expresses infinity, not-a-number, or negative zero, the CBOR object will have tag 268 and the appropriate format. - - * If the number's exponent is at least 2^64 or less than -(2^64), the CBOR object will have tag 264 and the appropriate format. - - * Otherwise, the CBOR object will have tag 4 and the appropriate format. - -Parameters: - - * bigValue: An arbitrary-precision decimal number. Can be null. - -Return Value: - -The given number encoded as a CBOR object. Returns CBORObject.Null if bigValue - is null. - - -### FromEFloat - - public static PeterO.Cbor.CBORObject FromEFloat( - PeterO.Numbers.EFloat bigValue); - -Generates a CBOR object from an arbitrary-precision binary floating-point number. The CBOR object is generated as follows (this is a change in version 4.0): - - * If the number is null, returns CBORObject.Null. - - * Otherwise, if the number expresses infinity, not-a-number, or negative zero, the CBOR object will have tag 269 and the appropriate format. - - * Otherwise, if the number's exponent is at least 2^64 or less than -(2^64), the CBOR object will have tag 265 and the appropriate format. - - * Otherwise, the CBOR object will have tag 5 and the appropriate format. - -Parameters: - - * bigValue: An arbitrary-precision binary floating-point number. Can be null. - -Return Value: - -The given number encoded as a CBOR object. Returns CBORObject.Null if bigValue - is null. - - -### FromEInteger - - public static PeterO.Cbor.CBORObject FromEInteger( - PeterO.Numbers.EInteger bigintValue); - -Generates a CBOR object from an arbitrary-precision integer. The CBOR object is generated as follows: - - * If the number is null, returns CBORObject.Null. - - * Otherwise, if the number is greater than or equal to -(2^64) and less than 2^64, the CBOR object will have the object type Integer and the appropriate value. - - * Otherwise, the CBOR object will have tag 2 (zero or positive) or 3 (negative) and the appropriate value. - -Parameters: - - * bigintValue: An arbitrary-precision integer. Can be null. - -Return Value: - -The given number encoded as a CBOR object. Returns CBORObject.Null if bigintValue - is null. - - -### FromERational - - public static PeterO.Cbor.CBORObject FromERational( - PeterO.Numbers.ERational bigValue); - -Generates a CBOR object from an arbitrary-precision rational number. The CBOR object is generated as follows (this is a change in version 4.0): - - * If the number is null, returns CBORObject.Null. - - * Otherwise, if the number expresses infinity, not-a-number, or negative zero, the CBOR object will have tag 270 and the appropriate format. - - * Otherwise, the CBOR object will have tag 30 and the appropriate format. - -Parameters: - - * bigValue: An arbitrary-precision rational number. Can be null. - -Return Value: - -The given number encoded as a CBOR object. Returns CBORObject.Null if bigValue - is null. - - -### FromFloatingPointBits - - public static PeterO.Cbor.CBORObject FromFloatingPointBits( - long floatingBits, - int byteCount); - -Generates a CBOR object from a floating-point number represented by its bits. - -Parameters: - - * floatingBits: The bits of a floating-point number number to write. - - * byteCount: The number of bytes of the stored floating-point number; this also specifies the format of the "floatingBits" parameter. This value can be 2 if "floatingBits"'s lowest (least significant) 16 bits identify the floating-point number in IEEE 754r binary16 format; or 4 if "floatingBits"'s lowest (least significant) 32 bits identify the floating-point number in IEEE 754r binary32 format; or 8 if "floatingBits" identifies the floating point number in IEEE 754r binary64 format. Any other values for this parameter are invalid. - -Return Value: - -A CBOR object storing the given floating-point number. - -Exceptions: - - * System.ArgumentException: -The parameter byteCount - is other than 2, 4, or 8. - - -### FromInt16 - - public static PeterO.Cbor.CBORObject FromInt16( - short value); - -Generates a CBOR object from a 16-bit signed integer. - -Parameters: - - * value: The parameter value - is a 16-bit signed integer. - -Return Value: - -A CBOR object generated from the given integer. - - -### FromInt32 - - public static PeterO.Cbor.CBORObject FromInt32( - int value); - -Generates a CBOR object from a 32-bit signed integer. - -Parameters: - - * value: The parameter value - is a 32-bit signed integer. - -Return Value: - -A CBOR object. + `true` if the objects are equal; otherwise, `false` . In this method, two objects are not equal if they don't have the same type or if one is null and the other isn't. - -### FromInt64 + +### FromFloatingPointBits - public static PeterO.Cbor.CBORObject FromInt64( - long value); + public static PeterO.Cbor.CBORObject FromFloatingPointBits( + long floatingBits, + int byteCount); -Generates a CBOR object from a 64-bit signed integer. +Generates a CBOR object from a floating-point number represented by its bits. Parameters: - * value: The parameter value - is a 64-bit signed integer. + * floatingBits: The bits of a floating-point number number to write. + + * byteCount: The number of bytes of the stored floating-point number; this also specifies the format of the "floatingBits" parameter. This value can be 2 if "floatingBits"'s lowest (least significant) 16 bits identify the floating-point number in IEEE 754r binary16 format; or 4 if "floatingBits"'s lowest (least significant) 32 bits identify the floating-point number in IEEE 754r binary32 format; or 8 if "floatingBits" identifies the floating point number in IEEE 754r binary64 format. Any other values for this parameter are invalid. Return Value: -A CBOR object. +A CBOR object storing the given floating-point number. + +Exceptions: + + * System.ArgumentException: +The parameter byteCount + is other than 2, 4, or 8. ### FromJSONBytes @@ -2226,6 +2389,37 @@ Either offset is less than count . + +### FromJSONString + + public static PeterO.Cbor.CBORObject FromJSONString( + string str, + PeterO.Cbor.CBOREncodeOptions options); + +Deprecated. Instead, use .FromJSONString(str, new JSONOptions("allowduplicatekeys=true")) or .FromJSONString(str, new JSONOptions("allowduplicatekeys=false")), as appropriate. + +Generates a CBOR object from a text string in JavaScript Object Notation (JSON) format, using the specified options to control the decoding process. Note that if a CBOR object is converted to JSON with `ToJSONString` , then the JSON is converted back to CBOR with this method, the new CBOR object will not necessarily be the same as the old CBOR object, especially if the old CBOR object uses data types not supported in JSON, such as integers in map keys. + +Parameters: + + * str: A text string in JSON format. The entire string must contain a single JSON object and not multiple objects. The string may not begin with a byte-order mark (U+FEFF). + + * options: Specifies options to control the decoding process. This method uses only the AllowDuplicateKeys property of this object. + +Return Value: + +A CBOR object containing the JSON data decoded. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + or options + is null. + + * PeterO.Cbor.CBORException: +The string is not in JSON format. + ### FromJSONString @@ -2261,8 +2455,6 @@ The string is not in JSON format. public static PeterO.Cbor.CBORObject FromObject( bool value); -Deprecated. Use FromBool instead. - Returns the CBOR true value or false value, depending on "value". Parameters: @@ -2279,17 +2471,16 @@ CBORObject.True if value is true; otherwise CBORObject.False. public static PeterO.Cbor.CBORObject FromObject( byte value); -Deprecated. Use FromByte instead. - -Generates a CBOR object from a byte. +Generates a CBOR object from a byte (0 to 255). Parameters: - * value: A byte. + * value: The parameter value + is a byte (from 0 to 255). Return Value: -A CBOR object. +A CBOR object generated from the given integer. ### FromObject @@ -2297,9 +2488,7 @@ A CBOR object. public static PeterO.Cbor.CBORObject FromObject( byte[] bytes); -Deprecated. Use FromByteArray instead. - -Generates a CBOR object from an array of 8-bit bytes. +Generates a CBOR object from an array of 8-bit bytes; the byte array is copied to a new byte array in this process. (This method can't be used to decode CBOR data from a byte array; for that, use the DecodeFromBytes method instead.). Parameters: @@ -2315,17 +2504,16 @@ A CBOR object where each element of the given byte array is copied to a new arra public static PeterO.Cbor.CBORObject FromObject( decimal value); -Deprecated. Use FromDecimal instead - Converts a.NET decimal to a CBOR object. Parameters: - * value: A Decimal. + * value: The parameter value + is a Decimal object. Return Value: -A CBORObject object. +A CBORObject object with the same value as the.NET decimal. ### FromObject @@ -2333,13 +2521,12 @@ A CBORObject object. public static PeterO.Cbor.CBORObject FromObject( double value); -Deprecated. Use FromDouble instead. - -Generates a CBOR object from a 64-bit floating-point number. +Generates a CBOR object from a 64-bit floating-point number. The input value can be a not-a-number (NaN) value (such as `Double.NaN` ); however, NaN values have multiple forms that are equivalent for many applications' purposes, and `Double.NaN` is only one of these equivalent forms. In fact, `CBORObject.FromObject(Double.NaN)` could produce a CBOR-encoded object that differs between DotNet and Java, because `Double.NaN` may have a different form in DotNet and Java (for example, the NaN value's sign may be negative in DotNet, but positive in Java). Parameters: - * value: A 64-bit floating-point number. + * value: The parameter value + is a 64-bit floating-point number. Return Value: @@ -2351,17 +2538,16 @@ A CBOR object generated from the given number. public static PeterO.Cbor.CBORObject FromObject( float value); -Deprecated. Use FromFloat instead. - -Generates a CBOR object from a 32-bit floating-point number. +Generates a CBOR object from a 32-bit floating-point number. The input value can be a not-a-number (NaN) value (such as `Single.NaN` in DotNet or Float.NaN in Java); however, NaN values have multiple forms that are equivalent for many applications' purposes, and `Single.NaN` / `Float.NaN` is only one of these equivalent forms. In fact, `CBORObject.FromObject(Single.NaN)` or `CBORObject.FromObject(Float.NaN)` could produce a CBOR-encoded object that differs between DotNet and Java, because `Single.NaN` / `Float.NaN` may have a different form in DotNet and Java (for example, the NaN value's sign may be negative in DotNet, but positive in Java). Parameters: - * value: A 32-bit floating-point number. + * value: The parameter value + is a 32-bit floating-point number. Return Value: -A CBOR object. +A CBOR object generated from the given number. ### FromObject @@ -2369,8 +2555,6 @@ A CBOR object. public static PeterO.Cbor.CBORObject FromObject( int value); -Deprecated. Use FromInt instead. - Generates a CBOR object from a 32-bit signed integer. Parameters: @@ -2404,8 +2588,6 @@ A CBOR array object where each element of the given array is copied to a new arr public static PeterO.Cbor.CBORObject FromObject( long value); -Deprecated. Use FromInt64 instead. - Generates a CBOR object from a 64-bit signed integer. Parameters: @@ -2444,7 +2626,7 @@ Generates a CBORObject from an arbitrary object. See the overload of this method Parameters: * obj: The parameter obj - is an arbitrary object, which can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. + is an arbitrary object, which can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. . @@ -2464,7 +2646,7 @@ Generates a CBORObject from an arbitrary object. See the overload of this method Parameters: * obj: The parameter obj - is an arbitrary object. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. + is an arbitrary object. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. . @@ -2560,7 +2742,7 @@ In the Java version, which has java.math.BigInteger, the following can be used i Parameters: - * obj: An arbitrary object to convert to a CBOR object. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. + * obj: An arbitrary object to convert to a CBOR object. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. . @@ -2593,7 +2775,7 @@ Generates a CBORObject from an arbitrary object. See the overload of this method Parameters: * obj: The parameter obj - is an arbitrary object. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. + is an arbitrary object. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. . @@ -2615,8 +2797,6 @@ The parameter options public static PeterO.Cbor.CBORObject FromObject( PeterO.Cbor.CBORObject value); -Deprecated. Don't use a function and use Nullable Reference Types to guard against nulls. - Generates a CBOR object from a CBOR object. Parameters: @@ -2636,8 +2816,6 @@ Same as value public static PeterO.Cbor.CBORObject FromObject( PeterO.Cbor.CBORObject[] array); -Deprecated. Use FromCBORArray instead. - Generates a CBOR object from an array of CBOR objects. Parameters: @@ -2646,7 +2824,7 @@ Generates a CBOR object from an array of CBOR objects. Return Value: -A CBOR object. +A CBOR object where each element of the given array is copied to a new array, or CBORObject.Null if the value is null. ### FromObject @@ -2654,17 +2832,24 @@ A CBOR object. public static PeterO.Cbor.CBORObject FromObject( PeterO.Numbers.EDecimal bigValue); -Deprecated. Use FromEDecimal instead. +Generates a CBOR object from a decimal number. The CBOR object is generated as follows (this is a change in version 4.0): + + * If the number is null, returns CBORObject.Null. + + * Otherwise, if the number expresses infinity, not-a-number, or negative zero, the CBOR object will have tag 268 and the appropriate format. + + * If the number's exponent is at least 2^64 or less than -(2^64), the CBOR object will have tag 264 and the appropriate format. -Generates a CBOR object from a decimal number. + * Otherwise, the CBOR object will have tag 4 and the appropriate format. Parameters: - * bigValue: An arbitrary-precision decimal number. + * bigValue: An arbitrary-precision decimal number. Can be null. Return Value: -The given number encoded as a CBOR object. +The given number encoded as a CBOR object. Returns CBORObject.Null if bigValue + is null. ### FromObject @@ -2672,17 +2857,24 @@ The given number encoded as a CBOR object. public static PeterO.Cbor.CBORObject FromObject( PeterO.Numbers.EFloat bigValue); -Deprecated. Use FromEFloat instead. +Generates a CBOR object from an arbitrary-precision binary floating-point number. The CBOR object is generated as follows (this is a change in version 4.0): + + * If the number is null, returns CBORObject.Null. + + * Otherwise, if the number expresses infinity, not-a-number, or negative zero, the CBOR object will have tag 269 and the appropriate format. + + * Otherwise, if the number's exponent is at least 2^64 or less than -(2^64), the CBOR object will have tag 265 and the appropriate format. -Generates a CBOR object from an arbitrary-precision binary floating-point number. + * Otherwise, the CBOR object will have tag 5 and the appropriate format. Parameters: - * bigValue: An arbitrary-precision binary floating-point number. + * bigValue: An arbitrary-precision binary floating-point number. Can be null. Return Value: -The given number encoded as a CBOR object. +The given number encoded as a CBOR object. Returns CBORObject.Null if bigValue + is null. ### FromObject @@ -2690,9 +2882,13 @@ The given number encoded as a CBOR object. public static PeterO.Cbor.CBORObject FromObject( PeterO.Numbers.EInteger bigintValue); -Deprecated. Use FromEInteger instead. +Generates a CBOR object from an arbitrary-precision integer. The CBOR object is generated as follows: + + * If the number is null, returns CBORObject.Null. + + * Otherwise, if the number is greater than or equal to -(2^64) and less than 2^64, the CBOR object will have the object type Integer and the appropriate value. -Generates a CBOR object from an arbitrary-precision integer. + * Otherwise, the CBOR object will have tag 2 (zero or positive) or 3 (negative) and the appropriate value. Parameters: @@ -2709,17 +2905,22 @@ The given number encoded as a CBOR object. Returns CBORObject.Null if bigint public static PeterO.Cbor.CBORObject FromObject( PeterO.Numbers.ERational bigValue); -Deprecated. Use FromERational instead. +Generates a CBOR object from an arbitrary-precision rational number. The CBOR object is generated as follows (this is a change in version 4.0): + + * If the number is null, returns CBORObject.Null. + + * Otherwise, if the number expresses infinity, not-a-number, or negative zero, the CBOR object will have tag 270 and the appropriate format. -Generates a CBOR object from an arbitrary-precision rational number. + * Otherwise, the CBOR object will have tag 30 and the appropriate format. Parameters: - * bigValue: An arbitrary-precision rational number. + * bigValue: An arbitrary-precision rational number. Can be null. Return Value: -The given number encoded as a CBOR object. +The given number encoded as a CBOR object. Returns CBORObject.Null if bigValue + is null. ### FromObject @@ -2727,15 +2928,14 @@ The given number encoded as a CBOR object. public static PeterO.Cbor.CBORObject FromObject( sbyte value); -Deprecated. Use FromSbyte instead - This API is not CLS-compliant. Converts a signed 8-bit integer to a CBOR object. Parameters: - * value: The input. + * value: The parameter value + is an 8-bit signed integer. Return Value: @@ -2747,13 +2947,12 @@ A CBORObject object. public static PeterO.Cbor.CBORObject FromObject( short value); -Deprecated. Use FromInt16 instead. - Generates a CBOR object from a 16-bit signed integer. Parameters: - * value: A 16-bit signed integer. + * value: The parameter value + is a 16-bit signed integer. Return Value: @@ -2765,8 +2964,6 @@ A CBOR object generated from the given integer. public static PeterO.Cbor.CBORObject FromObject( string strValue); -Deprecated. Use FromString instead. - Generates a CBOR object from a text string. Parameters: @@ -2777,14 +2974,17 @@ Generates a CBOR object from a text string. A CBOR object representing the string, or CBORObject.Null if stringValue is null. +Exceptions: + + * System.ArgumentException: +The string contains an unpaired surrogate code point. + ### FromObject public static PeterO.Cbor.CBORObject FromObject( uint value); -Deprecated. Use FromUInt instead - This API is not CLS-compliant. Converts a 32-bit unsigned integer to a CBOR object. @@ -2803,8 +3003,6 @@ A CBORObject object. public static PeterO.Cbor.CBORObject FromObject( ulong value); -Deprecated. Use FromUInt64 instead - This API is not CLS-compliant. Converts a 64-bit unsigned integer to a CBOR object. @@ -2823,8 +3021,6 @@ A CBORObject object. public static PeterO.Cbor.CBORObject FromObject( ushort value); -Deprecated. Use FromUShort instead - This API is not CLS-compliant. Converts a 16-bit unsigned integer to a CBOR object. @@ -2837,191 +3033,119 @@ Converts a 16-bit unsigned integer to a CBOR object. A CBORObject object. - + ### FromObjectAndTag public static PeterO.Cbor.CBORObject FromObjectAndTag( - object valueObValue, - int smallTag); + object o, + ulong tag); -Deprecated. Use FromCBORObjectAndTag instead. +This API is not CLS-compliant. -Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). +Generates a CBOR object from an arbitrary object and gives the resulting object a tag. Parameters: - * valueObValue: The parameter, an arbitrary object, which can be null. - - * smallTag: A 32-bit integer that specifies a tag number. - -Return Value: + * o: The parameter o + is an arbitrary object, which can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. -A CBOR object where the object valueObValue - is given the tag smallTag . -Exceptions: + * tag: A 64-bit integer that specifies a tag number. The tag number 55799 can be used to mark a "self-described CBOR" object. This document does not attempt to list all CBOR tags and their meanings. An up-to-date list can be found at the CBOR Tags registry maintained by the Internet Assigned Numbers Authority( iana.org/assignments/cbor-tags ). - * System.ArgumentException: -The parameter smallTag - is less than 0. +Return Value: + +A CBOR object where the object o + is converted to a CBOR object and given the tag tag + . If "valueOb" is null, returns a version of CBORObject.Null with the given tag. ### FromObjectAndTag public static PeterO.Cbor.CBORObject FromObjectAndTag( - object valueObValue, + object valueOb, PeterO.Numbers.EInteger bigintTag); -Deprecated. Use FromCBORObjectAndTag instead. - Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). Parameters: - * valueObValue: An arbitrary object, which can be null. + * valueOb: The parameter valueOb + is an arbitrary object, which can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. - * bigintTag: Tag number. - -Return Value: - -A CBOR object where the object valueObValue - is given the tag bigintTag . - -### FromSbyte - - public static PeterO.Cbor.CBORObject FromSbyte( - sbyte value); - -This API is not CLS-compliant. - -Converts a signed 8-bit integer to a CBOR object. - -Parameters: - - * value: The parameter value - is an 8-bit signed integer. - -Return Value: - -A CBORObject object. - - -### FromSimpleValue - - public static PeterO.Cbor.CBORObject FromSimpleValue( - int simpleValue); - -Creates a CBOR object from a simple value number. - -Parameters: - - * simpleValue: The parameter simpleValue - is a 32-bit signed integer. + * bigintTag: Tag number. The tag number 55799 can be used to mark a "self-described CBOR" object. This document does not attempt to list all CBOR tags and their meanings. An up-to-date list can be found at the CBOR Tags registry maintained by the Internet Assigned Numbers Authority( iana.org/assignments/cbor-tags ). Return Value: -A CBOR object. +A CBOR object where the object valueOb + is converted to a CBOR object and given the tag bigintTag +. If valueOb + is null, returns a version of CBORObject.Null with the given tag. Exceptions: * System.ArgumentException: -The parameter simpleValue - is less than 0, greater than 255, or from 24 through 31. - - -### FromSingle - - public static PeterO.Cbor.CBORObject FromSingle( - float value); - -Generates a CBOR object from a 32-bit floating-point number. The input value can be a not-a-number (NaN) value (such as `Single.NaN` in DotNet or Float.NaN in Java); however, NaN values have multiple forms that are equivalent for many applications' purposes, and `Single.NaN` / `Float.NaN` is only one of these equivalent forms. In fact, `CBORObject.FromSingle(Single.NaN)` or `CBORObject.FromSingle(Float.NaN)` could produce a CBOR-encoded object that differs between DotNet and Java, because `Single.NaN` / `Float.NaN` may have a different form in DotNet and Java (for example, the NaN value's sign may be negative in DotNet, but positive in Java). - -Parameters: +The parameter bigintTag + is less than 0 or greater than 2^64-1. - * value: The parameter value - is a 32-bit floating-point number. + * System.ArgumentNullException: +The parameter bigintTag + is null. -Return Value: + +### FromObjectAndTag -A CBOR object generated from the given number. + public static PeterO.Cbor.CBORObject FromObjectAndTag( + object valueObValue, + int smallTag); - -### FromString +Generates a CBOR object from an arbitrary object and gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag). - public static PeterO.Cbor.CBORObject FromString( - string strValue); +Parameters: -Generates a CBOR object from a text string. + * valueObValue: The parameter valueObValue + is an arbitrary object, which can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. -Parameters: +. - * strValue: A text string value. Can be null. + * smallTag: A 32-bit integer that specifies a tag number. The tag number 55799 can be used to mark a "self-described CBOR" object. This document does not attempt to list all CBOR tags and their meanings. An up-to-date list can be found at the CBOR Tags registry maintained by the Internet Assigned Numbers Authority ( iana.org/assignments/cbor-tags ). Return Value: -A CBOR object representing the string, or CBORObject.Null if stringValue is null. +A CBOR object where the object valueObValue + is converted to a CBOR object and given the tag smallTag +. If "valueOb" is null, returns a version of CBORObject.Null with the given tag. Exceptions: * System.ArgumentException: -The string contains an unpaired surrogate code point. - - -### FromUInt - - public static PeterO.Cbor.CBORObject FromUInt( - uint value); - -This API is not CLS-compliant. - -Converts a 32-bit unsigned integer to a CBOR object. - -Parameters: - - * value: A 32-bit unsigned integer. - -Return Value: - -A CBORObject object. - - -### FromUInt64 - - public static PeterO.Cbor.CBORObject FromUInt64( - ulong value); - -This API is not CLS-compliant. - -Converts a 64-bit unsigned integer to a CBOR object. - -Parameters: - - * value: A 64-bit unsigned integer. - -Return Value: - -A CBORObject object. - - -### FromUShort +The parameter smallTag + is less than 0. - public static PeterO.Cbor.CBORObject FromUShort( - ushort value); + +### FromSimpleValue -This API is not CLS-compliant. + public static PeterO.Cbor.CBORObject FromSimpleValue( + int simpleValue); -Converts a 16-bit unsigned integer to a CBOR object. +Creates a CBOR object from a simple value number. Parameters: - * value: A 16-bit unsigned integer. + * simpleValue: The parameter simpleValue + is a 32-bit signed integer. Return Value: -A CBORObject object. +A CBOR object. + +Exceptions: + + * System.ArgumentException: +The parameter simpleValue + is less than 0, greater than 255, or from 24 through 31. ### GetAllTags @@ -3061,37 +3185,18 @@ Calculates the hash code of this object. The hash code for a given instance of t A 32-bit hash code. - -### GetOrDefault - - public PeterO.Cbor.CBORObject GetOrDefault( - int key, - PeterO.Cbor.CBORObject defaultValue); - -Gets the value of a CBOR object by integer index in this array, or a default value if that value is not found. - -Parameters: - - * key: An arbitrary object. If this is a CBOR map, this parameter is converted to a CBOR object serving as the key to the map or index to the array, and can be null. If this is a CBOR array, the key must be an integer 0 or greater and less than the size of the array, and may be any object convertible to a CBOR integer. - - * defaultValue: A value to return if an item with the given key doesn't exist, or if the CBOR object is an array and the key is not an integer 0 or greater and less than the size of the array. - -Return Value: - -The CBOR object referred to by index or key in this array or map. If this is a CBOR map, returns `null` (not `CBORObject.Null` ) if an item with the given key doesn't exist. - - + ### GetOrDefault public PeterO.Cbor.CBORObject GetOrDefault( - PeterO.Cbor.CBORObject cborkey, + object key, PeterO.Cbor.CBORObject defaultValue); Gets the value of a CBOR object by integer index in this array or by CBOR object key in this map, or a default value if that value is not found. Parameters: - * cborkey: An arbitrary CBORObject. If this is a CBOR map, this parameter is converted to a CBOR object serving as the key to the map or index to the array, and can be null. If this is a CBOR array, the key must be an integer 0 or greater and less than the size of the array, and may be any object convertible to a CBOR integer. + * key: An arbitrary object. If this is a CBOR map, this parameter is converted to a CBOR object serving as the key to the map or index to the array, and can be null. If this is a CBOR array, the key must be an integer 0 or greater and less than the size of the array, and may be any object convertible to a CBOR integer. * defaultValue: A value to return if an item with the given key doesn't exist, or if the CBOR object is an array and the key is not an integer 0 or greater and less than the size of the array. @@ -3099,25 +3204,6 @@ Gets the value of a CBOR object by integer index in this array or by CBOR object The CBOR object referred to by index or key in this array or map. If this is a CBOR map, returns `null` (not `CBORObject.Null` ) if an item with the given key doesn't exist. - -### GetOrDefault - - public PeterO.Cbor.CBORObject GetOrDefault( - string key, - PeterO.Cbor.CBORObject defaultValue); - -Gets the value of a CBOR object by string key in a map, or a default value if that value is not found. - -Parameters: - - * key: An arbitrary string. If this is a CBOR map, this parameter is converted to a CBOR object serving as the key to the map or index to the array, and can be null. If this is a CBOR array, defaultValue is returned. - - * defaultValue: A value to return if an item with the given key doesn't exist, or if the CBOR object is an array. - -Return Value: - -The CBOR object referred to by index or key in this array or map. If this is a CBOR map, returns `null` (not `CBORObject.Null` ) if an item with the given key doesn't exist. - ### HasMostInnerTag @@ -3332,8 +3418,6 @@ The parameter bigTagValue int index, object valueOb); -Deprecated. Use the CBORObject overload instead. - Inserts an object at the specified position in this CBOR array. Parameters: @@ -3356,33 +3440,108 @@ The parameter valueOb has an unsupported type; or index is not a valid index into this array. - -### Insert + +### IsInfinity - public PeterO.Cbor.CBORObject Insert( - int index, - PeterO.Cbor.CBORObject cborObj); + public bool IsInfinity(); + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsInfinity()). + +Gets a value indicating whether this CBOR object represents infinity. + +Return Value: + + `true` if this CBOR object represents infinity; otherwise, `false` . + + +### IsNaN + + public bool IsNaN(); + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsNaN()). + +Gets a value indicating whether this CBOR object represents a not-a-number value (as opposed to whether this object does not express a number). + +Return Value: + + `true` if this CBOR object represents a not-a-number value (as opposed to whether this object does not represent a number as defined by the IsNumber property or `isNumber()` method in Java); otherwise, `false` . -Inserts a CBORObject at the specified position in this CBOR array. + +### IsNegativeInfinity + + public bool IsNegativeInfinity(); + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsNegativeInfinity()). + +Gets a value indicating whether this CBOR object represents negative infinity. + +Return Value: + + `true` if this CBOR object represents negative infinity; otherwise, `false` . + + +### IsPositiveInfinity + + public bool IsPositiveInfinity(); + +Deprecated. Instead, use the following: (cbor.IsNumber && cbor.AsNumber().IsPositiveInfinity()). + +Gets a value indicating whether this CBOR object represents positive infinity. + +Return Value: + + `true` if this CBOR object represents positive infinity; otherwise, `false` . + + +### Multiply + + public static PeterO.Cbor.CBORObject Multiply( + PeterO.Cbor.CBORObject first, + PeterO.Cbor.CBORObject second); + +Deprecated. Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Multiply() method. + +Multiplies two CBOR numbers. Parameters: - * index: Index starting at 0 to insert at. + * first: The parameter first + is a CBOR object. - * cborObj: A CBORObject representing the value. + * second: The parameter second + is a CBOR object. Return Value: -This instance. +The product of the two numbers. Exceptions: - * System.InvalidOperationException: -This object is not an array. - * System.ArgumentException: -The parameter index - is not a valid index into this array. +Either or both operands are not numbers (as opposed to Not-a-Number, NaN). + + * System.ArgumentNullException: +The parameter first + or second + is null. + + +### Negate + + public PeterO.Cbor.CBORObject Negate(); + +Deprecated. Instead, convert this object to a number (with .AsNumber()), and use that number's .Negate() method. + +Gets this object's value with the sign reversed. + +Return Value: + +The reversed-sign form of this number. + +Exceptions: + + * System.InvalidOperationException: +This object does not represent a number (for this purpose, infinities and not-a-number or NaN values, but not CBORObject.Null, are considered numbers). ### NewArray @@ -3417,6 +3576,52 @@ Creates a new empty CBOR map that ensures that keys are stored in the order in w A new CBOR map. + +### Operator `+` + + public static PeterO.Cbor.CBORObject operator +( + PeterO.Cbor.CBORObject a, + PeterO.Cbor.CBORObject b); + +Deprecated. May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. + +Does an addition on two CBOR objects and returns their result. + +Parameters: + + * a: The parameter a + is a CBOR object. + + * b: The parameter b + is a CBOR object. + +Return Value: + +The sum of the two objects. + + +### Operator `/` + + public static PeterO.Cbor.CBORObject operator /( + PeterO.Cbor.CBORObject a, + PeterO.Cbor.CBORObject b); + +Deprecated. May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. + +Divides a CBORObject object by the value of a CBORObject object. + +Parameters: + + * a: The parameter a + is a CBOR object. + + * b: The parameter b + is a CBOR object. + +Return Value: + +The quotient of the two objects. + ### Operator `>` @@ -3517,6 +3722,75 @@ Returns whether one object's value is up to another's. The parameter a is null. + +### Operator `%` + + public static PeterO.Cbor.CBORObject operator %( + PeterO.Cbor.CBORObject a, + PeterO.Cbor.CBORObject b); + +Deprecated. May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. + +Finds the remainder that results when a CBORObject object is divided by the value of a CBORObject object. + +Parameters: + + * a: The parameter a + is a CBOR object. + + * b: The parameter b + is a CBOR object. + +Return Value: + +The remainder of the two numbers. + + +### Operator `*` + + public static PeterO.Cbor.CBORObject operator *( + PeterO.Cbor.CBORObject a, + PeterO.Cbor.CBORObject b); + +Deprecated. May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. + +Multiplies a CBORObject object by the value of a CBORObject object. + +Parameters: + + * a: The parameter a + is a CBOR object. + + * b: The parameter b + is a CBOR object. + +Return Value: + +The product of the two numbers. + + +### Operator `-` + + public static PeterO.Cbor.CBORObject operator -( + PeterO.Cbor.CBORObject a, + PeterO.Cbor.CBORObject b); + +Deprecated. May be removed in the next major version. Consider converting the objects to CBOR numbers and performing the operation there. + +Subtracts a CBORObject object from a CBORObject object. + +Parameters: + + * a: The parameter a + is a CBOR object. + + * b: The parameter b + is a CBOR object. + +Return Value: + +The difference of the two objects. + ### Read @@ -3598,6 +3872,39 @@ An I/O error occurred. * PeterO.Cbor.CBORException: The data stream contains invalid encoding or is not in JSON format. + +### ReadJSON + + public static PeterO.Cbor.CBORObject ReadJSON( + System.IO.Stream stream, + PeterO.Cbor.CBOREncodeOptions options); + +Deprecated. Instead, use .ReadJSON(stream, new JSONOptions("allowduplicatekeys=true")) or .ReadJSON(stream, new JSONOptions("allowduplicatekeys=false")), as appropriate. + +Generates a CBOR object from a data stream in JavaScript Object Notation (JSON) format, using the specified options to control the decoding process. The JSON stream may begin with a byte-order mark (U+FEFF). Since version 2.0, the JSON stream can be in UTF-8, UTF-16, or UTF-32 encoding; the encoding is detected by assuming that the first character read must be a byte-order mark or a nonzero basic character (U+0001 to U+007F). (In previous versions, only UTF-8 was allowed.). + +Parameters: + + * stream: A readable data stream. The sequence of bytes read from the data stream must contain a single JSON object and not multiple objects. + + * options: Contains options to control the JSON decoding process. This method uses only the AllowDuplicateKeys property of this object. + +Return Value: + +A CBOR object containing the JSON data decoded. + +Exceptions: + + * System.ArgumentNullException: +The parameter stream + is null. + + * System.IO.IOException: +An I/O error occurred. + + * PeterO.Cbor.CBORException: +The data stream contains invalid encoding or is not in JSON format. + ### ReadJSON @@ -3746,6 +4053,36 @@ The parameter stream * PeterO.Cbor.CBORException: There was an error in reading or parsing the data, including if the last CBOR object was read only partially. + +### Remainder + + public static PeterO.Cbor.CBORObject Remainder( + PeterO.Cbor.CBORObject first, + PeterO.Cbor.CBORObject second); + +Deprecated. Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Remainder() method. + +Finds the remainder that results when a CBORObject object is divided by the value of a CBOR object. + +Parameters: + + * first: The parameter first + is a CBOR object. + + * second: The parameter second + is a CBOR object. + +Return Value: + +The remainder of the two numbers. + +Exceptions: + + * System.ArgumentNullException: +The parameter first + or second + is null. + ### Remove @@ -3817,30 +4154,6 @@ Returns "true" if the object was removed. Returns "false" if the given index is * System.InvalidOperationException: This object is not a CBOR array. - -### Set - - public PeterO.Cbor.CBORObject Set( - int key, - PeterO.Cbor.CBORObject mapValue); - -Sets the value of a CBORObject of type Array at the given index to the given value. - -Parameters: - - * key: This parameter must be a 32-bit signed integer( `int` ) identifying the index (starting from 0) of the item to set in the array. - - * mapValue: An CBORObject representing the value. - -Return Value: - -This instance. - -Exceptions: - - * System.InvalidOperationException: -MapValue is not a an array. - ### Set @@ -3848,8 +4161,6 @@ MapValue is not a an array. object key, object valueOb); -Deprecated. Use the CBORObject overload instead. - Maps an object to a key in this CBOR map, or adds the value if the key doesn't exist. If this is a CBOR array, instead sets the value at the given index to the given value. Parameters: @@ -3873,33 +4184,38 @@ The parameter key has an unsupported type, or this instance is a CBOR array and key is less than 0, is the size of this array or greater, or is not a 32-bit signed integer ( `int` ). - -### Set + +### Subtract - public PeterO.Cbor.CBORObject Set( - PeterO.Cbor.CBORObject mapKey, - PeterO.Cbor.CBORObject mapValue); + public static PeterO.Cbor.CBORObject Subtract( + PeterO.Cbor.CBORObject first, + PeterO.Cbor.CBORObject second); -Maps an object to a key in this CBOR map, or adds the value if the key doesn't exist. +Deprecated. Instead, convert both CBOR objects to numbers (with .AsNumber()), and use the first number's .Subtract() method. + +Finds the difference between two CBOR number objects. Parameters: - * mapKey: If this instance is a CBOR map, this parameter is an object representing the key, which will be converted to a CBORObject; in this case, this parameter can be null, in which case this value is converted to CBORObject.Null. + * first: The parameter first + is a CBOR object. - * mapValue: A CBORObject representing the value, which should be of type CBORType.Map. + * second: The parameter second + is a CBOR object. Return Value: -This instance. +The difference of the two objects. Exceptions: - * System.InvalidOperationException: -This object is not a map. - * System.ArgumentException: -The parameter mapValue - or this instance is a CBOR array. +Either or both operands are not numbers (as opposed to Not-a-Number, NaN). + + * System.ArgumentNullException: +The parameter first + or second + is null. ### ToJSONBytes @@ -3952,7 +4268,7 @@ A byte array containing the converted in JSON format. * The string will not begin with a byte-order mark (U+FEFF); RFC 8259 (the JSON specification) forbids placing a byte-order mark at the beginning of a JSON string. - * Byte strings are converted to Base64 URL without whitespace or padding by default (see section 3.4.5.3 of RFC 8949). A byte string will instead be converted to traditional base64 without whitespace and with padding if it has tag 22, or base16 for tag 23. (To create a CBOR object with a given tag, call the `CBORObject.FromCBORObjectAndTag` method and pass the CBOR object and the desired tag number to that method.) + * Byte strings are converted to Base64 URL without whitespace or padding by default (see section 3.4.5.3 of RFC 8949). A byte string will instead be converted to traditional base64 without whitespace and with padding if it has tag 22, or base16 for tag 23. (To create a CBOR object with a given tag, call the `CBORObject.FromObjectAndTag` method and pass the CBOR object and the desired tag number to that method.) * Rational numbers will be converted to their exact form, if possible, otherwise to a high-precision approximation. (The resulting approximation could overflow to infinity, in which case the rational number is converted to null.) @@ -4596,11 +4912,11 @@ Writes an arbitrary object to a CBOR data stream, using the specified options fo * String objects. The strings will be encoded using definite-length encoding regardless of their length. - * Any object accepted by the FromObject method. + * Any object accepted by the FromObject static methods. Parameters: - * objValue: The arbitrary object to be serialized. Can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. + * objValue: The arbitrary object to be serialized. Can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. . @@ -4661,7 +4977,7 @@ The parameter stream PeterO.Numbers.EDecimal bignum, System.IO.Stream stream); -Writes a decimal floating-point number in CBOR format to a data stream, as though it were converted to a CBOR object via CBORObject.FromEDecimal(EDecimal) and then written out. +Writes a decimal floating-point number in CBOR format to a data stream, as though it were converted to a CBOR object via CBORObject.FromObject(EDecimal) and then written out. Parameters: @@ -4685,7 +5001,7 @@ An I/O error occurred. PeterO.Numbers.EFloat bignum, System.IO.Stream stream); -Writes a binary floating-point number in CBOR format to a data stream, as though it were converted to a CBOR object via CBORObject.FromEFloat(EFloat) and then written out. +Writes a binary floating-point number in CBOR format to a data stream, as though it were converted to a CBOR object via CBORObject.FromObject(EFloat) and then written out. Parameters: @@ -4733,7 +5049,7 @@ An I/O error occurred. PeterO.Numbers.ERational rational, System.IO.Stream stream); -Writes a rational number in CBOR format to a data stream, as though it were converted to a CBOR object via CBORObject.FromERational(ERational) and then written out. +Writes a rational number in CBOR format to a data stream, as though it were converted to a CBOR object via CBORObject.FromObject(ERational) and then written out. Parameters: @@ -5043,7 +5359,7 @@ Converts an arbitrary object to a text string in JavaScript Object Notation (JSO Parameters: * obj: The parameter obj - is an arbitrary object. Can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data, and whenever possible, the application should limit this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. + is an arbitrary object. Can be null. NOTE: For security reasons, whenever possible, an application should not base this parameter on user input or other externally supplied data unless the application limits this parameter's inputs to types specially handled by this method (such as `int` or `String` ) and/or to plain-old-data types (POCO or POJO types) within the control of the application. If the plain-old-data type references other data types, those types should likewise meet either criterion above. . diff --git a/docs/PeterO.Cbor.JSONOptions.md b/docs/PeterO.Cbor.JSONOptions.md index 6a71f51f..62b4b99b 100644 --- a/docs/PeterO.Cbor.JSONOptions.md +++ b/docs/PeterO.Cbor.JSONOptions.md @@ -56,7 +56,7 @@ Initializes a new instance of the [PeterO.Cbor.JSONOptions](PeterO.Cbor.JSONOpti Parameters: - * paramString: A string setting forth the options to use. This is a semicolon-separated list of options, each of which has a key and a value separated by an equal sign ("="). Whitespace and line separators are not allowed to appear between the semicolons or between the equal signs, nor may the string begin or end with whitespace. The string can be empty, but cannot be null. The following is an example of this parameter: `base64padding=false;replacesurrogates=true` . The key can be any one of the following where the letters can be any combination of basic upper-case and/or basic lower-case letters: `base64padding` , `replacesurrogates` , `allowduplicatekeys` , `preservenegativezero` , `numberconversion` , `writebasic` , `keepkeyorder` . Other keys are ignored in this version of the CBOR library. (Keys are compared using a basic case-insensitive comparison, in which two strings are equal if they match after converting the basic upper-case letters A to Z (U+0041 to U+005A) in both strings to basic lower-case letters.) If two or more key/value pairs have equal keys (in a basic case-insensitive comparison), the value given for the last such key is used. The first four keys just given can have a value of `1` , `true` , `yes` , or `on` (where the letters can be any combination of basic upper-case and/or basic lower-case letters), which means true, and any other value meaning false. The last key, `numberconversion` , can have a value of any name given in the `JSONOptions.ConversionMode` enumeration (where the letters can be any combination of basic upper-case and/or basic lower-case letters), and any other value is unrecognized. (If the `numberconversion` key is not given, its value is treated as `intorfloat` (formerly `full` in versions earlier than 5.0). If that key is given, but has an unrecognized value, an exception is thrown.) For example, `base64padding=Yes` and `base64padding=1` both set the `Base64Padding` property to true, and `numberconversion=double` sets the `NumberConversion` property to `ConversionMode.Double` . + * paramString: A string setting forth the options to use. This is a semicolon-separated list of options, each of which has a key and a value separated by an equal sign ("="). Whitespace and line separators are not allowed to appear between the semicolons or between the equal signs, nor may the string begin or end with whitespace. The string can be empty, but cannot be null. The following is an example of this parameter: `base64padding=false;replacesurrogates=true` . The key can be any one of the following where the letters can be any combination of basic upper-case and/or basic lower-case letters: `base64padding` , `replacesurrogates` , `allowduplicatekeys` , `preservenegativezero` , `numberconversion` , `writebasic` , `keepkeyorder` . Other keys are ignored in this version of the CBOR library. (Keys are compared using a basic case-insensitive comparison, in which two strings are equal if they match after converting the basic upper-case letters A to Z (U+0041 to U+005A) in both strings to basic lower-case letters.) If two or more key/value pairs have equal keys (in a basic case-insensitive comparison), the value given for the last such key is used. The first four keys just given can have a value of `1` , `true` , `yes` , or `on` (where the letters can be any combination of basic upper-case and/or basic lower-case letters), which means true, and any other value meaning false. The last key, `numberconversion` , can have a value of any name given in the `JSONOptions.ConversionMode` enumeration (where the letters can be any combination of basic upper-case and/or basic lower-case letters), and any other value is unrecognized. (If the `numberconversion` key is not given, its value is treated as `full` . If that key is given, but has an unrecognized value, an exception is thrown.) For example, `base64padding=Yes` and `base64padding=1` both set the `Base64Padding` property to true, and `numberconversion=double` sets the `NumberConversion` property to `ConversionMode.Double` . Exceptions: diff --git a/docs/PeterO.Cbor.PODOptions.md b/docs/PeterO.Cbor.PODOptions.md index 1ec5e1df..160591f8 100644 --- a/docs/PeterO.Cbor.PODOptions.md +++ b/docs/PeterO.Cbor.PODOptions.md @@ -71,7 +71,7 @@ Gets a value indicating whether property, field, and method names are converted If "useCamelCase" is `true` : - * In the .NET version, for each eligible property or field name, the word "Is" is removed from the name if the name starts with that word, then the name is converted to camel case, meaning the first letter in the name is converted to a basic lower-case letter if it's a basic upper-case letter ("A" to "Z"). (For example, "Name" and "IsName" both become "name", and "IsIsName" becomes "isName".) + * In the .NET version, for each eligible property or field name, the word "Is" is removed from the name if the name starts with that word, then the name is converted to camel case, meaning the first letter in the name is converted to a basic lower-case letter if it's a basic upper-case letter ("A" to "Z"). (For example, "Name" and "IsName" both become "name".) * In the Java version: For each eligible method name, the word "get", "set", or "is" is removed from the name if the name starts with that word, then the name is converted to camel case. (For example, "getName", "setName", and "isName" all become "name".) For each eligible field name, the word "is" is removed from the name if the name starts with that word, then the name is converted to camel case. (For example, "name" and "isName" both become "name".) diff --git a/docs/PeterO.DataUtilities.md b/docs/PeterO.DataUtilities.md index e69de29b..00b4c89f 100644 --- a/docs/PeterO.DataUtilities.md +++ b/docs/PeterO.DataUtilities.md @@ -0,0 +1,661 @@ +## PeterO.DataUtilities + + public static class DataUtilities + +Contains methods useful for reading and writing text strings. It is designed to have no dependencies other than the basic runtime class library. Many of these methods work with text encoded in UTF-8, an encoding form of the Unicode Standard which uses one byte to encode the most basic characters and two to four bytes to encode other characters. For example, the `GetUtf8` method converts a text string to an array of bytes in UTF-8. + +In C# and Java, text strings are represented as sequences of 16-bit values called `char` s. These sequences are well-formed under UTF-16, a 16-bit encoding form of Unicode, except if they contain unpaired surrogate code points. (A surrogate code point is used to encode supplementary characters, those with code points U+10000 or higher, in UTF-16. A surrogate pair is a high surrogate, U+D800 to U+DBFF, followed by a low surrogate, U+DC00 to U+DFFF. An unpaired surrogate code point is a surrogate not appearing in a surrogate pair.) Many of the methods in this class allow setting the behavior to follow when unpaired surrogate code points are found in text strings, such as throwing an error or treating the unpaired surrogate as a replacement character (U+FFFD). + +### Member Summary +* [CodePointAt(string, int)](#CodePointAt_string_int) - Gets the Unicode code point at the given index of the string. +* [CodePointAt(string, int, int)](#CodePointAt_string_int_int) - Gets the Unicode code point at the given index of the string. +* [CodePointBefore(string, int)](#CodePointBefore_string_int) - Gets the Unicode code point just before the given index of the string. +* [CodePointBefore(string, int, int)](#CodePointBefore_string_int_int) - Gets the Unicode code point just before the given index of the string. +* [CodePointCompare(string, string)](#CodePointCompare_string_string) - Compares two strings in Unicode code point order. +* [CodePointLength(string)](#CodePointLength_string) - Finds the number of Unicode code points in the given text string. +* [GetUtf8Bytes(string, bool)](#GetUtf8Bytes_string_bool) - Encodes a string in UTF-8 as a byte array. +* [GetUtf8Bytes(string, bool, bool)](#GetUtf8Bytes_string_bool_bool) - Encodes a string in UTF-8 as a byte array. +* [GetUtf8Length(string, bool)](#GetUtf8Length_string_bool) - Calculates the number of bytes needed to encode a string in UTF-8. +* [GetUtf8String(byte[], bool)](#GetUtf8String_byte_bool) - Generates a text string from a UTF-8 byte array. +* [GetUtf8String(byte[], int, int, bool)](#GetUtf8String_byte_int_int_bool) - Generates a text string from a portion of a UTF-8 byte array. +* [ReadUtf8(System.IO.Stream, int, System.Text.StringBuilder, bool)](#ReadUtf8_System_IO_Stream_int_System_Text_StringBuilder_bool) - Reads a string in UTF-8 encoding from a data stream. +* [ReadUtf8FromBytes(byte[], int, int, System.Text.StringBuilder, bool)](#ReadUtf8FromBytes_byte_int_int_System_Text_StringBuilder_bool) - Reads a string in UTF-8 encoding from a byte array. +* [ReadUtf8ToString(System.IO.Stream)](#ReadUtf8ToString_System_IO_Stream) - Reads a string in UTF-8 encoding from a data stream in full and returns that string. +* [ReadUtf8ToString(System.IO.Stream, int, bool)](#ReadUtf8ToString_System_IO_Stream_int_bool) - Reads a string in UTF-8 encoding from a data stream and returns that string. +* [ToLowerCaseAscii(string)](#ToLowerCaseAscii_string) - Returns a string with the basic upper-case letters A to Z (U+0041 to U+005A) converted to the corresponding basic lower-case letters. +* [ToUpperCaseAscii(string)](#ToUpperCaseAscii_string) - Returns a string with the basic lower-case letters A to Z (U+0061 to U+007A) converted to the corresponding basic upper-case letters. +* [WriteUtf8(string, int, int, System.IO.Stream, bool)](#WriteUtf8_string_int_int_System_IO_Stream_bool) - Writes a portion of a string in UTF-8 encoding to a data stream. +* [WriteUtf8(string, int, int, System.IO.Stream, bool, bool)](#WriteUtf8_string_int_int_System_IO_Stream_bool_bool) - Writes a portion of a string in UTF-8 encoding to a data stream. +* [WriteUtf8(string, System.IO.Stream, bool)](#WriteUtf8_string_System_IO_Stream_bool) - Writes a string in UTF-8 encoding to a data stream. + + +### CodePointAt + + public static int CodePointAt( + string str, + int index); + +Gets the Unicode code point at the given index of the string. + +Parameters: + + * str: The parameter str + is a text string. + + * index: Index of the current position into the string. + +Return Value: + +The Unicode code point at the given position. Returns -1 if index + is 0 or less, or is greater than or equal to the string's length. Returns the replacement character (U+FFFD) if the code point at that position is an unpaired surrogate code point. If the return value is 65536 (0x10000) or greater, the code point takes up two UTF-16 code units. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + +### CodePointAt + + public static int CodePointAt( + string str, + int index, + int surrogateBehavior); + +Gets the Unicode code point at the given index of the string. + +The following example shows how to iterate a text string code point by code point, terminating the loop when an unpaired surrogate is found. + + for (var i = 0;i= 0x10000) { i++; /* Supplementary code point */ } } + + . + +Parameters: + + * str: The parameter str + is a text string. + + * index: Index of the current position into the string. + + * surrogateBehavior: Specifies what kind of value to return if the code point at the given index is an unpaired surrogate code point: if 0, return the replacement character (U + FFFD); if 1, return the value of the surrogate code point; if neither 0 nor 1, return -1. + +Return Value: + +The Unicode code point at the given position. Returns -1 if index + is 0 or less, or is greater than or equal to the string's length. Returns a value as specified under surrogateBehavior + if the code point at that position is an unpaired surrogate code point. If the return value is 65536 (0x10000) or greater, the code point takes up two UTF-16 code units. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + +### CodePointBefore + + public static int CodePointBefore( + string str, + int index); + +Gets the Unicode code point just before the given index of the string. + +Parameters: + + * str: The parameter str + is a text string. + + * index: Index of the current position into the string. + +Return Value: + +The Unicode code point at the previous position. Returns -1 if index + is 0 or less, or is greater than or equal to the string's length. Returns the replacement character (U+FFFD) if the code point at the previous position is an unpaired surrogate code point. If the return value is 65536 (0x10000) or greater, the code point takes up two UTF-16 code units. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + +### CodePointBefore + + public static int CodePointBefore( + string str, + int index, + int surrogateBehavior); + +Gets the Unicode code point just before the given index of the string. + +Parameters: + + * str: The parameter str + is a text string. + + * index: Index of the current position into the string. + + * surrogateBehavior: Specifies what kind of value to return if the previous code point is an unpaired surrogate code point: if 0, return the replacement character (U+FFFD); if 1, return the value of the surrogate code point; if neither 0 nor 1, return -1. + +Return Value: + +The Unicode code point at the previous position. Returns -1 if index + is 0 or less, or is greater than or equal to the string's length. Returns a value as specified under surrogateBehavior + if the code point at the previous position is an unpaired surrogate code point. If the return value is 65536 (0x10000) or greater, the code point takes up two UTF-16 code units. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + +### CodePointCompare + + public static int CodePointCompare( + string strA, + string strB); + +Compares two strings in Unicode code point order. Unpaired surrogate code points are treated as individual code points. + +Parameters: + + * strA: The first string. Can be null. + + * strB: The second string. Can be null. + +Return Value: + +A value indicating which string is " less" or " greater" . 0: Both strings are equal or null. Less than 0: a is null and b isn't; or the first code point that's different is less in A than in B; or b starts with a and is longer than a. Greater than 0: b is null and a isn't; or the first code point that's different is greater in A than in B; or a starts with b and is longer than b. + + +### CodePointLength + + public static int CodePointLength( + string str); + +Finds the number of Unicode code points in the given text string. Unpaired surrogate code points increase this number by 1. This is not necessarily the length of the string in "char" s. + +Parameters: + + * str: The parameter str + is a text string. + +Return Value: + +The number of Unicode code points in the given string. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + +### GetUtf8Bytes + + public static byte[] GetUtf8Bytes( + string str, + bool replace); + +Encodes a string in UTF-8 as a byte array. This method does not insert a byte-order mark (U+FEFF) at the beginning of the encoded byte array. + +REMARK: It is not recommended to use `Encoding.UTF8.GetBytes` in.NET, or the `getBytes()` method in Java to do this. For instance, `getBytes()` encodes text strings in a default (so not fixed) character encoding, which can be undesirable. + +Parameters: + + * str: The parameter str + is a text string. + + * replace: If true, replaces unpaired surrogate code points with the replacement character (U+FFFD). If false, stops processing when an unpaired surrogate code point is seen. + +Return Value: + +The string encoded in UTF-8. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + * System.ArgumentException: +The string contains an unpaired surrogate code point and replace + is false, or an internal error occurred. + + +### GetUtf8Bytes + + public static byte[] GetUtf8Bytes( + string str, + bool replace, + bool lenientLineBreaks); + +Encodes a string in UTF-8 as a byte array. This method does not insert a byte-order mark (U+FEFF) at the beginning of the encoded byte array. + +REMARK: It is not recommended to use `Encoding.UTF8.GetBytes` in.NET, or the `getBytes()` method in Java to do this. For instance, `getBytes()` encodes text strings in a default (so not fixed) character encoding, which can be undesirable. + +Parameters: + + * str: The parameter str + is a text string. + + * replace: If true, replaces unpaired surrogate code points with the replacement character (U+FFFD). If false, stops processing when an unpaired surrogate code point is seen. + + * lenientLineBreaks: If true, replaces carriage return (CR) not followed by line feed (LF) and LF not preceded by CR with CR-LF pairs. + +Return Value: + +The string encoded in UTF-8. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + * System.ArgumentException: +The string contains an unpaired surrogate code point and replace + is false, or an internal error occurred. + + +### GetUtf8Length + + public static long GetUtf8Length( + string str, + bool replace); + +Calculates the number of bytes needed to encode a string in UTF-8. + +Parameters: + + * str: The parameter str + is a text string. + + * replace: If true, treats unpaired surrogate code points as having 3 UTF-8 bytes (the UTF-8 length of the replacement character U+FFFD). + +Return Value: + +The number of bytes needed to encode the given string in UTF-8, or -1 if the string contains an unpaired surrogate code point and replace + is false. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null. + + +### GetUtf8String + + public static string GetUtf8String( + byte[] bytes, + bool replace); + +Generates a text string from a UTF-8 byte array. + +Parameters: + + * bytes: A byte array containing text encoded in UTF-8. + + * replace: If true, replaces invalid encoding with the replacement character (U+FFFD). If false, stops processing when invalid UTF-8 is seen. + +Return Value: + +A string represented by the UTF-8 byte array. + +Exceptions: + + * System.ArgumentNullException: +The parameter bytes + is null. + + * System.ArgumentException: +The string is not valid UTF-8 and replace + is false. + + +### GetUtf8String + + public static string GetUtf8String( + byte[] bytes, + int offset, + int bytesCount, + bool replace); + +Generates a text string from a portion of a UTF-8 byte array. + +Parameters: + + * bytes: A byte array containing text encoded in UTF-8. + + * offset: Offset into the byte array to start reading. + + * bytesCount: Length, in bytes, of the UTF-8 text string. + + * replace: If true, replaces invalid encoding with the replacement character (U+FFFD). If false, stops processing when invalid UTF-8 is seen. + +Return Value: + +A string represented by the UTF-8 byte array. + +Exceptions: + + * System.ArgumentNullException: +The parameter bytes + is null. + + * System.ArgumentException: +The portion of the byte array is not valid UTF-8 and replace + is false. + + * System.ArgumentException: +The parameter offset + is less than 0, bytesCount + is less than 0, or offset plus bytesCount is greater than the length of "data" . + + +### ReadUtf8 + + public static int ReadUtf8( + System.IO.Stream stream, + int bytesCount, + System.Text.StringBuilder builder, + bool replace); + +Reads a string in UTF-8 encoding from a data stream. + +Parameters: + + * stream: A readable data stream. + + * bytesCount: The length, in bytes, of the string. If this is less than 0, this function will read until the end of the stream. + + * builder: A string builder object where the resulting string will be stored. + + * replace: If true, replaces invalid encoding with the replacement character (U+FFFD). If false, stops processing when an unpaired surrogate code point is seen. + +Return Value: + +0 if the entire string was read without errors, -1 if the string is not valid UTF-8 and replace + is false, or -2 if the end of the stream was reached before the last character was read completely (which is only the case if bytesCount + is 0 or greater). + +Exceptions: + + * System.IO.IOException: +An I/O error occurred. + + * System.ArgumentNullException: +The parameter stream + is null or builder + is null. + + +### ReadUtf8FromBytes + + public static int ReadUtf8FromBytes( + byte[] data, + int offset, + int bytesCount, + System.Text.StringBuilder builder, + bool replace); + +Reads a string in UTF-8 encoding from a byte array. + +Parameters: + + * data: A byte array containing a UTF-8 text string. + + * offset: Offset into the byte array to start reading. + + * bytesCount: Length, in bytes, of the UTF-8 text string. + + * builder: A string builder object where the resulting string will be stored. + + * replace: If true, replaces invalid encoding with the replacement character (U+FFFD). If false, stops processing when invalid UTF-8 is seen. + +Return Value: + +0 if the entire string was read without errors, or -1 if the string is not valid UTF-8 and replace + is false. + +Exceptions: + + * System.ArgumentNullException: +The parameter data + is null or builder + is null. + + * System.ArgumentException: +The parameter offset + is less than 0, bytesCount + is less than 0, or offset plus bytesCount is greater than the length of data +. + + +### ReadUtf8ToString + + public static string ReadUtf8ToString( + System.IO.Stream stream); + +Reads a string in UTF-8 encoding from a data stream in full and returns that string. Replaces invalid encoding with the replacement character (U+FFFD). + +Parameters: + + * stream: A readable data stream. + +Return Value: + +The string read. + +Exceptions: + + * System.IO.IOException: +An I/O error occurred. + + * System.ArgumentNullException: +The parameter stream + is null. + + +### ReadUtf8ToString + + public static string ReadUtf8ToString( + System.IO.Stream stream, + int bytesCount, + bool replace); + +Reads a string in UTF-8 encoding from a data stream and returns that string. + +Parameters: + + * stream: A readable data stream. + + * bytesCount: The length, in bytes, of the string. If this is less than 0, this function will read until the end of the stream. + + * replace: If true, replaces invalid encoding with the replacement character (U+FFFD). If false, throws an error if an unpaired surrogate code point is seen. + +Return Value: + +The string read. + +Exceptions: + + * System.IO.IOException: +An I/O error occurred; or, the string is not valid UTF-8 and replace + is false. + + * System.ArgumentNullException: +The parameter stream + is null. + + +### ToLowerCaseAscii + + public static string ToLowerCaseAscii( + string str); + +Returns a string with the basic upper-case letters A to Z (U+0041 to U+005A) converted to the corresponding basic lower-case letters. Other characters remain unchanged. + +Parameters: + + * str: The parameter str + is a text string. + +Return Value: + +The converted string, or null if str + is null. + + +### ToUpperCaseAscii + + public static string ToUpperCaseAscii( + string str); + +Returns a string with the basic lower-case letters A to Z (U+0061 to U+007A) converted to the corresponding basic upper-case letters. Other characters remain unchanged. + +Parameters: + + * str: The parameter str + is a text string. + +Return Value: + +The converted string, or null if str + is null. + + +### WriteUtf8 + + public static int WriteUtf8( + string str, + int offset, + int length, + System.IO.Stream stream, + bool replace); + +Writes a portion of a string in UTF-8 encoding to a data stream. + +Parameters: + + * str: A string to write. + + * offset: The Index starting at 0 where the string portion to write begins. + + * length: The length of the string portion to write. + + * stream: A writable data stream. + + * replace: If true, replaces unpaired surrogate code points with the replacement character (U+FFFD). If false, stops processing when an unpaired surrogate code point is seen. + +Return Value: + +0 if the entire string portion was written; or -1 if the string portion contains an unpaired surrogate code point and replace + is false. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null or stream + is null. + + * System.IO.IOException: +An I/O error occurred. + + * System.ArgumentException: +Either offset + or length + is less than 0 or greater than str + 's length, or str + 's length minus offset + is less than length +. + + +### WriteUtf8 + + public static int WriteUtf8( + string str, + int offset, + int length, + System.IO.Stream stream, + bool replace, + bool lenientLineBreaks); + +Writes a portion of a string in UTF-8 encoding to a data stream. + +Parameters: + + * str: A string to write. + + * offset: The Index starting at 0 where the string portion to write begins. + + * length: The length of the string portion to write. + + * stream: A writable data stream. + + * replace: If true, replaces unpaired surrogate code points with the replacement character (U+FFFD). If false, stops processing when an unpaired surrogate code point is seen. + + * lenientLineBreaks: If true, replaces carriage return (CR) not followed by line feed (LF) and LF not preceded by CR with CR-LF pairs. + +Return Value: + +0 if the entire string portion was written; or -1 if the string portion contains an unpaired surrogate code point and replace + is false. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null or stream + is null. + + * System.ArgumentException: +The parameter offset + is less than 0, length + is less than 0, or offset + plus length + is greater than the string's length. + + * System.IO.IOException: +An I/O error occurred. + + +### WriteUtf8 + + public static int WriteUtf8( + string str, + System.IO.Stream stream, + bool replace); + +Writes a string in UTF-8 encoding to a data stream. + +Parameters: + + * str: A string to write. + + * stream: A writable data stream. + + * replace: If true, replaces unpaired surrogate code points with the replacement character (U+FFFD). If false, stops processing when an unpaired surrogate code point is seen. + +Return Value: + +0 if the entire string was written; or -1 if the string contains an unpaired surrogate code point and replace + is false. + +Exceptions: + + * System.ArgumentNullException: +The parameter str + is null or stream + is null. + + * System.IO.IOException: +An I/O error occurred.