diff --git a/CBOR/CBOR.csproj b/CBOR/CBOR.csproj index bad1082e..3a861853 100644 --- a/CBOR/CBOR.csproj +++ b/CBOR/CBOR.csproj @@ -3,16 +3,22 @@ netstandard1.0; net6.0 True - 5.0-alpha1 + 5.0.0-alpha1 Peter Occil A C# implementation of Concise Binary Object Representation (CBOR), a general-purpose binary data format defined in RFC 8949. A C# implementation of Concise Binary Object Representation (CBOR), a general-purpose binary data format defined in RFC 8949. - 2021. Written by Peter O. Any copyright to this work is released to the Public Domain. In case this is not possible, this work is also licensed under Creative Commons Zero (CC0). + Written by Peter O. Any copyright to this work is released to the Public Domain. In case this is not possible, this work is also licensed under Creative Commons Zero (CC0). Peter Occil PeterO.Cbor CC0-1.0 https://github.com/peteroupc/CBOR +Version 5.0: + +- Alpha version +- Some deprecated features from earlier versions were obsoleted. +- Attempt to make the library trimmable by making use of reflection optional. + Version 4.5: - Add support for JSON Pointers and JSON Patches diff --git a/CBOR/PeterO/Cbor/CBORDoubleBits.cs b/CBOR/PeterO/Cbor/CBORDoubleBits.cs index e5c96b11..63237d83 100644 --- a/CBOR/PeterO/Cbor/CBORDoubleBits.cs +++ b/CBOR/PeterO/Cbor/CBORDoubleBits.cs @@ -60,7 +60,7 @@ public long AsInt64(object obj) { return 0; } if (neg && b == (0x43eL << 52)) { - return long.MinValue; + return Int64.MinValue; } if ((b >> 52) >= 0x43e) { throw new OverflowException("This object's value is out of range"); diff --git a/CBOR/PeterO/Cbor/CBORInteger.cs b/CBOR/PeterO/Cbor/CBORInteger.cs index c6c21222..9b03803f 100644 --- a/CBOR/PeterO/Cbor/CBORInteger.cs +++ b/CBOR/PeterO/Cbor/CBORInteger.cs @@ -14,7 +14,7 @@ internal class CBORInteger : ICBORNumber { public object Abs(object obj) { var val = (long)obj; - return (val == int.MinValue) ? (EInteger.One << 63) : ((val < 0) ? + return (val == Int32.MinValue) ? (EInteger.One << 63) : ((val < 0) ? -val : obj); } @@ -54,7 +54,7 @@ public float AsSingle(object obj) { public bool CanFitInDouble(object obj) { var intItem = (long)obj; - if (intItem == long.MinValue) { + if (intItem == Int64.MinValue) { return true; } intItem = (intItem < 0) ? -intItem : intItem; @@ -66,7 +66,7 @@ public bool CanFitInDouble(object obj) { public bool CanFitInInt32(object obj) { var val = (long)obj; - return val >= int.MinValue && val <= int.MaxValue; + return val >= Int32.MinValue && val <= Int32.MaxValue; } public bool CanFitInInt64(object obj) { @@ -75,7 +75,7 @@ public bool CanFitInInt64(object obj) { public bool CanFitInSingle(object obj) { var intItem = (long)obj; - if (intItem == long.MinValue) { + if (intItem == Int64.MinValue) { return true; } intItem = (intItem < 0) ? -intItem : intItem; @@ -87,7 +87,7 @@ public bool CanFitInSingle(object obj) { public bool CanTruncatedIntFitInInt32(object obj) { var val = (long)obj; - return val >= int.MinValue && val <= int.MaxValue; + return val >= Int32.MinValue && val <= Int32.MaxValue; } public bool CanTruncatedIntFitInUInt64(object obj) { @@ -133,7 +133,7 @@ public bool IsNumberZero(object obj) { } public object Negate(object obj) { - return (((long)obj) == long.MinValue) ? (EInteger.One << 63) : + return (((long)obj) == Int64.MinValue) ? (EInteger.One << 63) : (-(long)obj); } diff --git a/CBOR/PeterO/Cbor/CBORUtilities.cs b/CBOR/PeterO/Cbor/CBORUtilities.cs index d8ba5885..9ae48471 100644 --- a/CBOR/PeterO/Cbor/CBORUtilities.cs +++ b/CBOR/PeterO/Cbor/CBORUtilities.cs @@ -1541,7 +1541,6 @@ public static int DoubleToHalfPrecisionIfSameValue(long bits) { return ((mant & ((1L << 42) - 1)) == 0) ? (sign | 0x7c00 | newmant) : -1; } else if (exp == 0 && mant == 0) { // positive or negative zero -always fits in half precision return sign; } else if (sexp >= 31) { // overflow return -1; diff --git a/CBOR/PeterO/Cbor/SharedRefs.cs b/CBOR/PeterO/Cbor/SharedRefs.cs index dec276a4..fc9f70eb 100644 --- a/CBOR/PeterO/Cbor/SharedRefs.cs +++ b/CBOR/PeterO/Cbor/SharedRefs.cs @@ -25,7 +25,7 @@ public CBORObject GetObject(long smallIndex) { if (smallIndex < 0) { throw new CBORException("Unexpected index"); } - if (smallIndex > int.MaxValue) { + if (smallIndex > Int32.MaxValue) { throw new CBORException("Index " + smallIndex + " is bigger than supported "); } diff --git a/CBOR/docs.xml b/CBOR/docs.xml index af84d536..bbaaa687 100644 --- a/CBOR/docs.xml +++ b/CBOR/docs.xml @@ -3353,8 +3353,7 @@ - - Generates a CBOR object from a 32-bit floating-point +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 @@ -3369,7 +3368,6 @@ The parameter is a 32-bit floating-point number. A CBOR object generated from the given number. - @@ -4178,6 +4176,25 @@ The parameter is less than 0, greater than 255, or from 24 through 31. + + + + 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). + The parameter is a + 32-bit floating-point number. + A CBOR object generated from the given number. + diff --git a/CBORTest/BEncodingTest.cs b/CBORTest/BEncodingTest.cs index def1908d..1ae86d20 100644 --- a/CBORTest/BEncodingTest.cs +++ b/CBORTest/BEncodingTest.cs @@ -48,10 +48,10 @@ public static void DoTestString(string value) { public void TestLong() { DoTestLong(0); DoTestLong(-1); - DoTestLong(int.MinValue); - DoTestLong(int.MaxValue); - DoTestLong(long.MinValue); - DoTestLong(long.MaxValue); + DoTestLong(Int32.MinValue); + DoTestLong(Int32.MaxValue); + DoTestLong(Int64.MinValue); + DoTestLong(Int64.MaxValue); } [Test] diff --git a/CBORTest/CBORNumberTest.cs b/CBORTest/CBORNumberTest.cs index 5d6a9b12..d972b7a5 100644 --- a/CBORTest/CBORNumberTest.cs +++ b/CBORTest/CBORNumberTest.cs @@ -733,12 +733,14 @@ public void TestEncodingZeros() { ToObjectTest.TestToFromObjectRoundTrip(-0.0); ToObjectTest.TestToFromObjectRoundTrip(-0.0f); - TestCommon.CompareTestEqual(ToCN(0.0), - CBORObject.FromDouble(-0.0).AsNumber().Negate()); + TestCommon.CompareTestEqual( + ToCN(0.0), + CBORObject.FromDouble(-0.0).AsNumber().Negate()); TestCommon.CompareTestEqual(ToCN(-0.0), CBORObject.FromDouble(0.0).AsNumber().Negate()); - TestCommon.CompareTestEqual(ToCN(0.0f), - CBORObject.FromSingle(-0.0f).AsNumber().Negate()); + TestCommon.CompareTestEqual( + ToCN(0.0f), + CBORObject.FromSingle(-0.0f).AsNumber().Negate()); TestCommon.CompareTestEqual(ToCN(-0.0f), CBORObject.FromSingle(0.0f).AsNumber().Negate()); diff --git a/CBORTest/RandomGenerator.cs b/CBORTest/RandomGenerator.cs index 57292566..52ef122c 100644 --- a/CBORTest/RandomGenerator.cs +++ b/CBORTest/RandomGenerator.cs @@ -253,7 +253,7 @@ public int NegativeBinomial(int trials, double p) { return 0; } if (p == 0.0) { - return int.MaxValue; + return Int32.MaxValue; } var count = 0; if (p == 0.5) { @@ -410,7 +410,7 @@ public int UniformInt(int minInclusive, int maxExclusive) { return minInclusive + this.UniformInt(maxExclusive - minInclusive); } else { long diff = maxExclusive - minInclusive; - return diff <= int.MaxValue ? minInclusive + + return diff <= Int32.MaxValue ? minInclusive + this.UniformInt((int)diff) : (int)(minInclusive + this.UniformLong(diff)); } } @@ -433,9 +433,9 @@ public long UniformLong(long minInclusive, long maxExclusive) { if (minInclusive >= 0) { return minInclusive + this.UniformLong(maxExclusive - minInclusive); } else { - if ((maxExclusive < 0 && long.MaxValue + maxExclusive < + if ((maxExclusive < 0 && Int64.MaxValue + maxExclusive < minInclusive) || - (maxExclusive > 0 && long.MinValue + maxExclusive > minInclusive) || + (maxExclusive > 0 && Int64.MinValue + maxExclusive > minInclusive) || minInclusive - maxExclusive < 0) { var b = new byte[8]; while (true) { @@ -502,7 +502,7 @@ public int UniformInt(int maxExclusive) { return ib; } int maxexc; - maxexc = int.MaxValue / maxExclusive * maxExclusive; + maxexc = Int32.MaxValue / maxExclusive * maxExclusive; while (true) { _ = this.valueIrg.GetBytes(b, 0, 4); ib = b[0] & 0xff; @@ -542,7 +542,7 @@ public long UniformLong(long maxExclusive) { throw new ArgumentException("maxExclusive(" + maxExclusive + ") is less than 0"); } - if (maxExclusive <= int.MaxValue) { + if (maxExclusive <= Int32.MaxValue) { return this.UniformInt((int)maxExclusive); } if (this.valueIrg is IRandomGenExtended rge) { @@ -551,7 +551,7 @@ public long UniformLong(long maxExclusive) { long maxexc; var b = new byte[8]; - maxexc = long.MaxValue / maxExclusive * maxExclusive; + maxexc = Int64.MaxValue / maxExclusive * maxExclusive; while (true) { _ = this.valueIrg.GetBytes(b, 0, 8); long lb = b[0] & 0xffL; diff --git a/CBORTest/RandomObjects.cs b/CBORTest/RandomObjects.cs index 1c59ba05..c4e37275 100644 --- a/CBORTest/RandomObjects.cs +++ b/CBORTest/RandomObjects.cs @@ -170,7 +170,7 @@ public static long RandomInt64(IRandomGenExtended rand) { } public static double RandomDouble(IRandomGenExtended rand, int exponent) { - if (exponent == int.MaxValue) { + if (exponent == Int32.MaxValue) { if (rand == null) { throw new ArgumentNullException(nameof(rand)); } @@ -211,7 +211,7 @@ public static float RandomSingle(IRandomGenExtended rand) { } public static float RandomSingle(IRandomGenExtended rand, int exponent) { - if (exponent == int.MaxValue) { + if (exponent == Int32.MaxValue) { if (rand == null) { throw new ArgumentNullException(nameof(rand)); } @@ -586,7 +586,7 @@ public static string RandomDecimalString( } } var bufferSize = (int)Math.Min( - int.MaxValue, + Int32.MaxValue, 8 + count + afterPointCount + exponentCount); var sb = new StringBuilder(bufferSize); if (r.GetInt32(2) == 0) { diff --git a/History.md b/History.md index e2c2a0ef..59ebaa99 100644 --- a/History.md +++ b/History.md @@ -1,6 +1,28 @@ Release notes --------------------- +### Version 4.5.3 + +- More bug fixes, including a fix to a problem that can occur when reading from compressed or network streams + +### Version 4.5.2 + +- Bug and regression fixes + +### Version 4.5.1 + +- Fix reported security issue + +### Version 4.5: + +- Add support for JSON Pointers and JSON Patches +- Add option to keep map key order when decoding CBOR and JSON +- Add option to write JSON using only ASCII characters +- CBORObject.ToString renders strings as ASCII +- 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. + ### Version 4.4.2 - Performance improvements in some cases, especially involving date/time conversions diff --git a/docs/APIDocs.md b/docs/APIDocs.md index 0aa5db49..0b06483a 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) - diff --git a/docs/PeterO.Cbor.CBORDataUtilities.md b/docs/PeterO.Cbor.CBORDataUtilities.md index ad821e69..5f7a3bf8 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. 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 3bacb14b..65a6f094 100644 --- a/docs/PeterO.Cbor.CBORObject.md +++ b/docs/PeterO.Cbor.CBORObject.md @@ -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,6 +102,7 @@ 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. @@ -98,6 +119,7 @@ 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) - Returns the CBOR true value or false value, depending on "value". * [FromObject(byte[])](#FromObject_byte) - Generates a CBOR object from a byte. Generates a CBOR object from an array of 8-bit bytes. @@ -140,38 +162,57 @@ The ReadJSON and FromJSONString methods currently have nesting depths of 1000. * [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) - 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(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. diff --git a/docs/PeterO.DataUtilities.md b/docs/PeterO.DataUtilities.md index 00b4c89f..e69de29b 100644 --- a/docs/PeterO.DataUtilities.md +++ b/docs/PeterO.DataUtilities.md @@ -1,661 +0,0 @@ -## 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.