PeterO.Cbor.CBORObject

PeterO.Cbor.CBORObject

public sealed class CBORObject :
    System.IComparable,
    System.IEquatable

Represents an object in Concise Binary Object Representation (CBOR) and contains methods for reading and writing CBOR data. CBOR is an Internet Standard and defined in RFC 8949.

Converting CBOR objects

There are many ways to get a CBOR object, including from bytes, objects, streams and JSON, as described below.

To and from byte arrays: The CBORObject.DecodeFromBytes method converts a byte array in CBOR format to a CBOR object. The EncodeToBytes method converts a CBOR object to its corresponding byte array in CBOR format.

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 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.

In addition, the CBORObject.WriteJSON method writes many kinds of objects as JSON 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 JSON data stream.

Comparison Considerations:

Instances of CBORObject should not be compared for equality using the "==" operator; it's possible to create two CBOR objects with the same value but not the same reference. (The "==" operator might only check if each side of the operator is the same instance.)

This class's natural ordering (under the CompareTo method) is consistent with the Equals method, meaning that two values that compare as equal under the CompareTo method are also equal under the Equals method; this is a change in version 4.0. Two otherwise equal objects with different tags are not treated as equal by both CompareTo and Equals. To strip the tags from a CBOR object before comparing, use the Untag method.

Thread Safety:

Certain CBOR objects are immutable (their values can't be changed), so they are inherently safe for use by multiple threads.

CBOR objects that are arrays, maps, and byte strings (whether or not they are tagged) are mutable, but this class doesn't attempt to synchronize reads and writes to those objects by multiple threads, so those objects are not thread safe without such synchronization.

One kind of CBOR object is called a map, or a list of key-value pairs. Keys can be any kind of CBOR object, including numbers, strings, arrays, and maps. However, untagged text strings (which means GetTags returns an empty array and the Type property, or "getType()" in Java, returns TextString) are the most suitable to use as keys; other kinds of CBOR object are much better used as map values instead, keeping in mind that some of them are not thread safe without synchronizing reads and writes to them.

To find the type of a CBOR object, call its Type property (or "getType()" in Java). The return value can be Integer, FloatingPoint, Boolean, SimpleValue, or TextString for immutable CBOR objects, and Array, Map, or ByteString for mutable CBOR objects.

Nesting Depth:

The DecodeFromBytes and Read methods can only read objects with a limited maximum depth of arrays and maps nested within other arrays and maps. The code sets this maximum depth to 500 (allowing more than enough nesting for most purposes), but it's possible that stack overflows in some runtimes might lower the effective maximum nesting depth. When the nesting depth goes above 500, the DecodeFromBytes and Read methods throw a CBORException.

The ReadJSON and FromJSONString methods currently have nesting depths of 1000.

Member Summary

False

public static readonly PeterO.Cbor.CBORObject False;

Represents the value false.

NaN

public static readonly PeterO.Cbor.CBORObject NaN;

A not-a-number value.

NegativeInfinity

public static readonly PeterO.Cbor.CBORObject NegativeInfinity;

The value negative infinity.

Null

public static readonly PeterO.Cbor.CBORObject Null;

Represents the value null.

PositiveInfinity

public static readonly PeterO.Cbor.CBORObject PositiveInfinity;

The value positive infinity.

True

public static readonly PeterO.Cbor.CBORObject True;

Represents the value true.

Undefined

public static readonly PeterO.Cbor.CBORObject Undefined;

Represents the value undefined.

Zero

public static readonly PeterO.Cbor.CBORObject Zero;

Gets a CBOR object for the number zero.

Count

public int Count { get; }

Gets the number of keys in this map, or the number of items in this array, or 0 if this item is neither an array nor a map.

Returns:

The number of keys in this map, or the number of items in this array, or 0 if this item is neither an array nor a map.

Entries

public System.Collections.Generic.ICollection Entries { get; }

Gets a collection of the key/value pairs stored in this CBOR object, if it's a map. Returns one entry for each key/value pair in the map. In general, the order in which those entries occur is undefined unless this is a map created using the NewOrderedMap method.

Returns:

A collection of the key/value pairs stored in this CBOR map, as a read-only view of those pairs. To avoid potential problems, the calling code should not modify the CBOR map while iterating over the returned collection.

Exceptions:

IsFalse

public bool IsFalse { get; }

Gets a value indicating whether this value is a CBOR false value, whether tagged or not.

Returns:

true if this value is a CBOR false value; otherwise, false .

IsNull

public bool IsNull { get; }

Gets a value indicating whether this CBOR object is a CBOR null value, whether tagged or not.

Returns:

true if this value is a CBOR null value; otherwise, false .

IsNumber

public bool IsNumber { get; }

Gets a value indicating whether this CBOR object stores a number (including infinity or a not-a-number or NaN value). Currently, this is true if this item is untagged and has a CBORType of Integer or FloatingPoint, or if this item has only one tag and that tag is 2, 3, 4, 5, 30, 264, 265, 268, 269, or 270 with the right data type.

Returns:

A value indicating whether this CBOR object stores a number.

IsTagged

public bool IsTagged { get; }

Gets a value indicating whether this data item has at least one tag.

Returns:

true if this data item has at least one tag; otherwise, false .

IsTrue

public bool IsTrue { get; }

Gets a value indicating whether this value is a CBOR true value, whether tagged or not.

Returns:

true if this value is a CBOR true value; otherwise, false .

IsUndefined

public bool IsUndefined { get; }

Gets a value indicating whether this value is a CBOR undefined value, whether tagged or not.

Returns:

true if this value is a CBOR undefined value; otherwise, false .

Item

public PeterO.Cbor.CBORObject this[string key] { get; set; }

Gets the value of a CBOR object in this map, using a string as the key.

Parameters:

Return Value:

The CBOR object referred to by key in this map. Returns null if an item with the given key doesn't exist.

Exceptions:

Keys

public System.Collections.Generic.ICollection Keys { get; }

Gets a collection of the keys of this CBOR object. In general, the order in which those keys occur is undefined unless this is a map created using the NewOrderedMap method.

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.

Exceptions:

MostInnerTag

public PeterO.Numbers.EInteger MostInnerTag { get; }

Gets the last defined tag for this CBOR data item, or -1 if the item is untagged.

Returns:

The last defined tag for this CBOR data item, or -1 if the item is untagged.

MostOuterTag

public PeterO.Numbers.EInteger MostOuterTag { get; }

Gets the outermost tag for this CBOR data item, or -1 if the item is untagged.

Returns:

The outermost tag for this CBOR data item, or -1 if the item is untagged.

SimpleValue

public int SimpleValue { get; }

Gets the simple value ID of this CBOR object, or -1 if the object is not a simple value. In this method, objects with a CBOR type of Boolean or SimpleValue are simple values, whether they are tagged or not.

Returns:

The simple value ID of this object if it's a simple value, or -1 if this object is not a simple value.

TagCount

public int TagCount { get; }

Gets the number of tags this object has.

Returns:

The number of tags this object has.

Type

public PeterO.Cbor.CBORType Type { get; }

Gets the general data type of this CBOR object. This method disregards the tags this object has, if any.

Returns:

The general data type of this CBOR object.

Values

public System.Collections.Generic.ICollection Values { get; }

Gets a collection of the values of this CBOR object, if it's a map or an array. If this object is a map, returns one value for each key in the map; in general, the order in which those keys occur is undefined unless this is a map created using the NewOrderedMap method. If this is an array, returns all the values of the array in the order they are listed. (This method can't be used to get the bytes in a CBOR byte string; for that, use the GetByteString method instead.).

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.

Exceptions:

Add

public PeterO.Cbor.CBORObject Add(
    object key,
    object valueOb);

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.

Parameters:

Return Value:

This instance.

Exceptions:

Add

public PeterO.Cbor.CBORObject Add(
    object obj);

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.

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));

.

Parameters:

Return Value:

This instance.

Exceptions:

Add

public PeterO.Cbor.CBORObject Add(
    PeterO.Cbor.CBORObject 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.

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));

.

Parameters:

Return Value:

This instance.

Exceptions:

ApplyJSONPatch

public PeterO.Cbor.CBORObject ApplyJSONPatch(
    PeterO.Cbor.CBORObject patch);

Returns a copy of this object after applying the operations in a JSON patch, in the form of a CBOR object. JSON patches are specified in RFC 6902 and their format is summarized in the remarks below.

Remarks: A JSON patch is an array with one or more maps. Each map has the following keys:

Parameters:

Return Value:

The result of the patch operation.

Exceptions:

AsBoolean

public bool AsBoolean();

Returns false if this object is a CBOR false, null, or undefined value (whether or not the object has tags); otherwise, true.

Return Value:

False if this object is a CBOR false, null, or undefined value; otherwise, true.

AsDouble

public double AsDouble();

Converts this object to a 64-bit floating point number.

Return Value:

The closest 64-bit floating point number to this object. The return value can be positive infinity or negative infinity if this value exceeds the range of a 64-bit floating point number.

Exceptions:

AsDoubleBits

public long AsDoubleBits();

Converts this object to the bits of a 64-bit floating-point number if this CBOR object's type is FloatingPoint. This method disregards the tags this object has, if any.

Return Value:

The bits of a 64-bit floating-point number stored by this object. The most significant bit is the sign (set means negative, clear means nonnegative); the next most significant 11 bits are the exponent area; and the remaining bits are the significand area. If all the bits of the exponent area are set and the significand area is 0, this indicates infinity. If all the bits of the exponent area are set and the significand area is other than 0, this indicates not-a-number (NaN).

Exceptions:

AsDoubleValue

public double AsDoubleValue();

Converts this object to a 64-bit floating-point number if this CBOR object's type is FloatingPoint. This method disregards the tags this object has, if any.

Return Value:

The 64-bit floating-point number stored by this object.

Exceptions:

AsEIntegerValue

public PeterO.Numbers.EInteger AsEIntegerValue();

Converts this object to an arbitrary-precision integer if this CBOR object's type is Integer. This method disregards the tags this object has, if any. (Note that CBOR stores untagged integers at least -(2^64) and less than 2^64.).

Return Value:

The integer stored by this object.

Exceptions:

AsInt32

public int AsInt32();

Converts this object to a 32-bit signed integer. Non-integer number values are converted to integers by discarding their fractional parts. (NOTE: To determine whether this method call can succeed, call AsNumber().CanTruncatedIntFitInInt32 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 32-bit signed integer before getting its value.

CBORObject obj = CBORObject.FromInt32(99999);
            if (obj.AsNumber().CanTruncatedIntFitInInt32()) {
            /* Not an Int32; handle the error */
            Console.WriteLine("Not a 32-bit integer."); } else {
            Console.WriteLine("The value is " + obj.AsInt32()); }

.

Return Value:

The closest 32-bit signed integer to this object.

Exceptions:

AsInt32Value

public int AsInt32Value();

Converts this object to a 32-bit signed integer if this CBOR object's type is Integer. This method disregards the tags this object has, if any.

The following example code (originally written in C# for the.NET Framework) shows a way to check whether a given CBOR object stores a 32-bit signed integer before getting its value.

CBORObject obj = CBORObject.FromInt32(99999);
            if (obj.CanValueFitInInt32()) { /* Not an Int32;
            handle the error */ Console.WriteLine("Not a 32-bit integer."); } else {
            Console.WriteLine("The value is " + obj.AsInt32Value()); }

.

Return Value:

The 32-bit signed integer stored by this object.

Exceptions:

AsInt64Value

public long AsInt64Value();

Converts this object to a 64-bit signed integer if this CBOR object's type is Integer. This method disregards the tags this object has, if any.

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.CanValueFitInInt64()) {
            /* Not an Int64; handle the error*/
            Console.WriteLine("Not a 64-bit integer."); } else {
            Console.WriteLine("The value is " + obj.AsInt64Value()); }

.

Return Value:

The 64-bit signed integer stored by this object.

Exceptions:

AsNumber

public PeterO.Cbor.CBORNumber AsNumber();

Converts this object to a CBOR number. (NOTE: To determine whether this method call can succeed, call the IsNumber property (isNumber() method in Java) before calling this method.).

Return Value:

The number represented by this object.

Exceptions:

AsSingle

public float AsSingle();

Converts this object to a 32-bit floating point number.

Return Value:

The closest 32-bit floating point number to this object. The return value can be positive infinity or negative infinity if this object's value exceeds the range of a 32-bit floating point number.

Exceptions:

AsString

public string AsString();

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<String>(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:

Gets this object's string.

Exceptions:

AtJSONPointer

public PeterO.Cbor.CBORObject AtJSONPointer(
    string pointer);

Gets the CBOR object referred to by a JSON Pointer according to RFC6901. For more information, see the overload taking a default value parameter.

Parameters:

Return Value:

An object within this CBOR object. Returns this object if pointer is the empty string (even if this object has a CBOR type other than array or map).

Exceptions:

AtJSONPointer

public PeterO.Cbor.CBORObject AtJSONPointer(
    string pointer,
    PeterO.Cbor.CBORObject defaultValue);

Gets the CBOR object referred to by a JSON Pointer according to RFC6901, or a default value if the operation fails. The syntax for a JSON Pointer is: '/' KEY '/' KEY [...] where KEY represents a key into the JSON object or its sub-objects in the hierarchy. For example, /foo/2/bar means the same as obj['foo'][2]['bar'] in JavaScript. If "~" and/or "/" occurs in a key, it must be escaped with "~0" or "~1", respectively, in a JSON pointer. JSON pointers also support the special key "-" (as in "/foo/-") to indicate the end of an array, but this method treats this key as an error since it refers to a nonexistent item. Indices to arrays (such as 2 in the example) must contain only basic digits 0 to 9 and no leading zeros. (Note that RFC 6901 was published before JSON was extended to support top-level values other than arrays and key-value dictionaries.).

Parameters:

Return Value:

An object within the specified JSON object. Returns this object if pointer is the empty string (even if this object has a CBOR type other than array or map). Returns defaultValue if the pointer is null, or if the pointer is invalid, or if there is no object at the given pointer, or the special key "-" appears in the pointer in the context of an array (not a map), or if the pointer is non-empty and this object has a CBOR type other than array or map.

CalcEncodedSize

public long CalcEncodedSize();

Calculates the number of bytes this CBOR object takes when serialized as a byte array using the EncodeToBytes() method. This calculation assumes that integers, lengths of maps and arrays, lengths of text and byte strings, and tag numbers are encoded in their shortest form; that floating-point numbers are encoded in their shortest value-preserving form; and that no indefinite-length encodings are used.

Return Value:

The number of bytes this CBOR object takes when serialized as a byte array using the EncodeToBytes() method.

Exceptions:

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:

CompareTo

public sealed int CompareTo(
    PeterO.Cbor.CBORObject other);

Compares two CBOR objects. This implementation was changed in version 4.0. In this implementation:

This method is consistent with the Equals method.

Parameters:

Return Value:

A negative number, if this value is less than the other object; or 0, if both values are equal; or a positive number, if this value is less than the other object or if the other object is null. This implementation returns a positive number if other is null, to conform to the.NET definition of CompareTo. This is the case even in the Java version of this library, for consistency's sake, even though implementations of Comparable.compareTo() in Java ought to throw an exception if they receive a null argument rather than treating null as less or greater than any object.

.

CompareToIgnoreTags

public int CompareToIgnoreTags(
    PeterO.Cbor.CBORObject other);

Compares this object and another CBOR object, ignoring the tags they have, if any. See the CompareTo method for more information on the comparison function.

Parameters:

Return Value:

Less than 0, if this value is less than the other object; or 0, if both values are equal; or greater than 0, if this value is less than the other object or if the other object is null.

ContainsKey

public bool ContainsKey(
    object objKey);

Determines whether a value of the given key exists in this object.

Parameters:

Return Value:

true if the given key is found, or false if the given key is not found or this object is not a map.

ContainsKey

public bool ContainsKey(
    PeterO.Cbor.CBORObject key);

Determines whether a value of the given key exists in this object.

Parameters:

Return Value:

true if the given key is found, or false if the given key is not found or this object is not a map.

ContainsKey

public bool ContainsKey(
    string key);

Determines whether a value of the given key exists in this object.

Parameters:

Return Value:

true if the given key (as a CBOR object) is found, or false if the given key is not found or this object is not a map.

DecodeFromBytes

public static PeterO.Cbor.CBORObject DecodeFromBytes(
    byte[] data);

Generates a CBOR object from an array of CBOR-encoded bytes.

Parameters:

Return Value:

A CBOR object decoded from the given byte array.

Exceptions:

DecodeFromBytes

public static PeterO.Cbor.CBORObject DecodeFromBytes(
    byte[] data,
    PeterO.Cbor.CBOREncodeOptions options);

Generates a CBOR object from an array of CBOR-encoded bytes, using the given CBOREncodeOptions object to control the decoding process.

The following example (originally written in C# for the.NET version) implements a method that decodes a text string from a CBOR byte array. It's successful only if the CBOR object contains an untagged text string.

private static String DecodeTextString(byte[] bytes) { if (bytes ==
            null) { throw new ArgumentNullException(nameof(mapObj));}
            if
            (bytes.Length == 0 || bytes[0]<0x60 || bytes[0]>0x7f) {throw new
            CBORException();} return CBORObject.DecodeFromBytes(bytes,
            CBOREncodeOptions.Default).AsString(); }

.

Parameters:

Return Value:

A CBOR object decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given options object.

Exceptions:

DecodeObjectFromBytes

public static object DecodeObjectFromBytes(
    byte[] data,
    PeterO.Cbor.CBOREncodeOptions enc,
    System.Type t);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes, using the given CBOREncodeOptions object to control the decoding process. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeObjectFromBytes

public static object DecodeObjectFromBytes(
    byte[] data,
    PeterO.Cbor.CBOREncodeOptions enc,
    System.Type t,
    PeterO.Cbor.CBORTypeMapper mapper,
    PeterO.Cbor.PODOptions pod);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes, using the given CBOREncodeOptions object to control the decoding process. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeObjectFromBytes

public static object DecodeObjectFromBytes(
    byte[] data,
    System.Type t);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeObjectFromBytes

public static object DecodeObjectFromBytes(
    byte[] data,
    System.Type t,
    PeterO.Cbor.CBORTypeMapper mapper,
    PeterO.Cbor.PODOptions pod);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeObjectFromBytes

public static T DecodeObjectFromBytes<T>(
    byte[] data);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeObjectFromBytes

public static T DecodeObjectFromBytes<T>(
    byte[] data,
    PeterO.Cbor.CBOREncodeOptions enc);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes, using the given CBOREncodeOptions object to control the decoding process. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeObjectFromBytes

public static T DecodeObjectFromBytes<T>(
    byte[] data,
    PeterO.Cbor.CBOREncodeOptions enc,
    PeterO.Cbor.CBORTypeMapper mapper,
    PeterO.Cbor.PODOptions pod);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes, using the given CBOREncodeOptions object to control the decoding process. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeObjectFromBytes

public static T DecodeObjectFromBytes<T>(
    byte[] data,
    PeterO.Cbor.CBORTypeMapper mapper,
    PeterO.Cbor.PODOptions pod);

Generates an object of an arbitrary type from an array of CBOR-encoded bytes. It is equivalent to DecodeFromBytes followed by ToObject. See the documentation for those methods for more information.

Parameters:

Return Value:

An object of the given type decoded from the given byte array. Returns null (as opposed to CBORObject.Null) if data is empty and the AllowEmpty property is set on the given CBOREncodeOptions object.

Exceptions:

DecodeSequenceFromBytes

public static PeterO.Cbor.CBORObject[] DecodeSequenceFromBytes(
    byte[] data);

Generates a sequence of CBOR objects from an array of CBOR-encoded bytes.

Parameters:

Return Value:

An array of CBOR objects decoded from the given byte array. Returns an empty array if data is empty.

Exceptions:

DecodeSequenceFromBytes

public static PeterO.Cbor.CBORObject[] DecodeSequenceFromBytes(
    byte[] data,
    PeterO.Cbor.CBOREncodeOptions options);

Generates a sequence of CBOR objects from an array of CBOR-encoded bytes.

Parameters:

Return Value:

An array of CBOR objects decoded from the given byte array. Returns an empty array if data is empty.

Exceptions:

EncodeToBytes

public byte[] EncodeToBytes(
    PeterO.Cbor.CBOREncodeOptions options);

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. For the CTAP2 (FIDO Client-to-Authenticator Protocol 2) canonical ordering, which is useful for implementing Web Authentication, call this method as follows: EncodeToBytes(new CBOREncodeOptions("ctap2canonical=true")) .

Parameters:

Return Value:

A byte array in CBOR format.

Exceptions:

EncodeToBytes

public byte[] EncodeToBytes();

Writes the binary representation of this CBOR object and returns a byte array of that representation. If the CBOR object contains CBOR maps, or is a CBOR map itself, the order in which the keys to the map are written out to the byte array is undefined unless the map was created using the NewOrderedMap method. The example code given in M:PeterO.Cbor.CBORObject.WriteTo(System.IO.Stream) can be used to write out certain keys of a CBOR map in a given order. For the CTAP2 (FIDO Client-to-Authenticator Protocol 2) canonical ordering, which is useful for implementing Web Authentication, call EncodeToBytes(new CBOREncodeOptions("ctap2canonical=true")) rather than this method.

Return Value:

A byte array in CBOR format.

Equals

public override bool Equals(
    object obj);

Determines whether this object and another object are equal and have the same type. Not-a-number values can be considered equal by this method.

Parameters:

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.

Equals

public sealed bool Equals(
    PeterO.Cbor.CBORObject other);

Compares the equality of two CBOR objects. Not-a-number values can be considered equal by this method.

Parameters:

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:

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:

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:

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:

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:

.

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:

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:

.

Return Value:

A CBOR object where the object cborObj is given the tag bigintTag .

Exceptions:

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:

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:

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:

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):

Parameters:

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):

Parameters:

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:

Parameters:

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):

Parameters:

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:

Return Value:

A CBOR object storing the given floating-point number.

Exceptions:

FromInt16

public static PeterO.Cbor.CBORObject FromInt16(
    short value);

Generates a CBOR object from a 16-bit signed integer.

Parameters:

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:

Return Value:

A CBOR object.

FromInt64

public static PeterO.Cbor.CBORObject FromInt64(
    long value);

Generates a CBOR object from a 64-bit signed integer.

Parameters:

Return Value:

A CBOR object.

FromJSONBytes

public static PeterO.Cbor.CBORObject FromJSONBytes(
    byte[] bytes);

Generates a CBOR object from a byte array in JavaScript Object Notation (JSON) format.

If a JSON object has duplicate keys, a CBORException is thrown.

Note that if a CBOR object is converted to JSON with ToJSONBytes , 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:

Return Value:

A CBOR object containing the JSON data decoded.

Exceptions:

FromJSONBytes

public static PeterO.Cbor.CBORObject FromJSONBytes(
    byte[] bytes,
    int offset,
    int count);

Generates a CBOR object from a byte array in JavaScript Object Notation (JSON) format.

If a JSON object has duplicate keys, a CBORException is thrown.

Note that if a CBOR object is converted to JSON with ToJSONBytes , 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:

Return Value:

A CBOR object containing the JSON data decoded.

Exceptions:

FromJSONBytes

public static PeterO.Cbor.CBORObject FromJSONBytes(
    byte[] bytes,
    int offset,
    int count,
    PeterO.Cbor.JSONOptions jsonoptions);

Generates a CBOR object from a byte array 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 ToJSONBytes , 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:

Return Value:

A CBOR object containing the JSON data decoded.

Exceptions:

FromJSONBytes

public static PeterO.Cbor.CBORObject FromJSONBytes(
    byte[] bytes,
    PeterO.Cbor.JSONOptions jsonoptions);

Generates a CBOR object from a byte array 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 ToJSONBytes , 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:

Return Value:

A CBOR object containing the JSON data decoded.

Exceptions:

FromJSONSequenceBytes

public static PeterO.Cbor.CBORObject[] FromJSONSequenceBytes(
    byte[] bytes);

Generates a list of CBOR objects from an array of bytes in JavaScript Object Notation (JSON) text sequence format (RFC 7464). The byte array must be in UTF-8 encoding and may not begin with a byte-order mark (U+FEFF).

Generally, each JSON text in a JSON text sequence is written as follows: Write a record separator byte (0x1e), then write the JSON text in UTF-8 (without a byte order mark, U+FEFF), then write the line feed byte (0x0a). RFC 7464, however, uses a more liberal syntax for parsing JSON text sequences.

Parameters:

Return Value:

A list of CBOR objects read from the JSON sequence. Objects that could not be parsed are replaced with null (as opposed to CBORObject.Null ) in the given list.

Exceptions:

FromJSONSequenceBytes

public static PeterO.Cbor.CBORObject[] FromJSONSequenceBytes(
    byte[] data,
    PeterO.Cbor.JSONOptions options);

Generates a list of CBOR objects from an array of bytes in JavaScript Object Notation (JSON) text sequence format (RFC 7464), using the specified options to control the decoding process. The byte array must be in UTF-8 encoding and may not begin with a byte-order mark (U+FEFF).

Generally, each JSON text in a JSON text sequence is written as follows: Write a record separator byte (0x1e), then write the JSON text in UTF-8 (without a byte order mark, U+FEFF), then write the line feed byte (0x0a). RFC 7464, however, uses a more liberal syntax for parsing JSON text sequences.

Parameters:

Return Value:

A list of CBOR objects read from the JSON sequence. Objects that could not be parsed are replaced with null (as opposed to CBORObject.Null ) in the given list.

Exceptions:

FromJSONString

public static PeterO.Cbor.CBORObject FromJSONString(
    string str);

Generates a CBOR object from a text string in JavaScript Object Notation (JSON) format.

If a JSON object has duplicate keys, a CBORException is thrown. This is a change in version 4.0.

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:

Return Value:

A CBOR object.

Exceptions:

FromJSONString

public static PeterO.Cbor.CBORObject FromJSONString(
    string str,
    int offset,
    int count);

Generates a CBOR object from a text string in JavaScript Object Notation (JSON) format.

If a JSON object has duplicate keys, a CBORException is thrown. This is a change in version 4.0.

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:

Return Value:

A CBOR object.

Exceptions:

FromJSONString

public static PeterO.Cbor.CBORObject FromJSONString(
    string str,
    int offset,
    int count,
    PeterO.Cbor.JSONOptions jsonoptions);

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:

Return Value:

A CBOR object containing the JSON data decoded.

Exceptions:

FromJSONString

public static PeterO.Cbor.CBORObject FromJSONString(
    string str,
    PeterO.Cbor.JSONOptions jsonoptions);

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:

Return Value:

A CBOR object containing the JSON data decoded.

Exceptions:

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    bool value);

Deprecated. Use FromBool instead.

Returns the CBOR true value or false value, depending on "value".

Parameters:

Return Value:

CBORObject.True if value is true; otherwise CBORObject.False.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    byte value);

Deprecated. Use FromByte instead.

Generates a CBOR object from a byte.

Parameters:

Return Value:

A CBOR object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    byte[] bytes);

Deprecated. Use FromByteArray instead.

Generates a CBOR object from an array of 8-bit bytes.

Parameters:

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.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    decimal value);

Deprecated. Use FromDecimal instead

Converts a.NET decimal to a CBOR object.

Parameters:

Return Value:

A CBORObject object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    double value);

Deprecated. Use FromDouble instead.

Generates a CBOR object from a 64-bit floating-point number.

Parameters:

Return Value:

A CBOR object generated from the given number.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    float value);

Deprecated. Use FromFloat instead.

Generates a CBOR object from a 32-bit floating-point number.

Parameters:

Return Value:

A CBOR object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    int value);

Deprecated. Use FromInt instead.

Generates a CBOR object from a 32-bit signed integer.

Parameters:

Return Value:

A CBOR object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    int[] array);

Generates a CBOR object from an array of 32-bit integers.

Parameters:

Return Value:

A CBOR array object where each element of the given array is copied to a new array, or CBORObject.Null if the value is null.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    long value);

Deprecated. Use FromInt64 instead.

Generates a CBOR object from a 64-bit signed integer.

Parameters:

Return Value:

A CBOR object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    long[] array);

Generates a CBOR object from an array of 64-bit integers.

Parameters:

Return Value:

A CBOR array object where each element of the given array is copied to a new array, or CBORObject.Null if the value is null.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    object obj);

Generates a CBORObject from an arbitrary object. See the overload of this method that takes CBORTypeMapper and PODOptions arguments.

Parameters:

.

Return Value:

A CBOR object corresponding to the given object. Returns CBORObject.Null if the object is null.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    object obj,
    PeterO.Cbor.CBORTypeMapper mapper);

Generates a CBORObject from an arbitrary object. See the overload of this method that takes CBORTypeMapper and PODOptions arguments.

Parameters:

.

Return Value:

A CBOR object corresponding to the given object. Returns CBORObject.Null if the object is null.

Exceptions:

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    object obj,
    PeterO.Cbor.CBORTypeMapper mapper,
    PeterO.Cbor.PODOptions options);

Generates a CBORObject from an arbitrary object, using the given options to control how certain objects are converted to CBOR objects. The following cases are checked in the logical order given (rather than the strict order in which they are implemented by this library):

REMARK: .NET enumeration ( Enum ) constants could also have been converted to text strings with ToString() , but that method will return multiple names if the given Enum object is a combination of Enum objects (e.g. if the object is FileAccess.Read | FileAccess.Write ). More generally, if Enums are converted to text strings, constants from Enum types with the Flags attribute, and constants from the same Enum type that share an underlying value, should not be passed to this method.

The following example (originally written in C# for the DotNet version) uses a CBORTypeMapper to change how DateTime objects are converted to CBOR. In this case, such objects are converted to CBOR objects with tag 1 that store numbers giving the number of seconds since the start of 1970.

var conv = new CBORTypeMapper().AddConverter(typeof(DateTime),
            CBORDateConverter.TaggedNumber);
            CBORObject obj = CBORObject.FromObject(DateTime.Now, conv);

The following example generates a CBOR object from a 64-bit signed integer that is treated as a 64-bit unsigned integer (such as DotNet's UInt64, which has no direct equivalent in the Java language), in the sense that the value is treated as 2^64 plus the original value if it's negative.

long x = -40L; /* Example 64-bit value treated as 2^64-40.*/
            CBORObject obj = CBORObject.FromObject(
            v < 0 ? EInteger.FromInt32(1).ShiftLeft(64).Add(v) :
            EInteger.FromInt64(v));

In the Java version, which has java.math.BigInteger, the following can be used instead:

long x = -40L; /* Example 64-bit value treated as 2^64-40.*/
            CBORObject obj = CBORObject.FromObject(
            v < 0 ? BigInteger.valueOf(1).shiftLeft(64).add(BigInteger.valueOf(v)) :
            BigInteger.valueOf(v));

Parameters:

Return Value:

A CBOR object corresponding to the given object. Returns CBORObject.Null if the object is null.

Exceptions:

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    object obj,
    PeterO.Cbor.PODOptions options);

Generates a CBORObject from an arbitrary object. See the overload of this method that takes CBORTypeMapper and PODOptions arguments.

Parameters:

.

Return Value:

A CBOR object corresponding to the given object. Returns CBORObject.Null if the object is null.

Exceptions:

FromObject

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:

Return Value:

Same as value , or "CBORObject.Null" is value is null.

FromObject

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:

Return Value:

A CBOR object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    PeterO.Numbers.EDecimal bigValue);

Deprecated. Use FromEDecimal instead.

Generates a CBOR object from a decimal number.

Parameters:

Return Value:

The given number encoded as a CBOR object.

FromObject

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.

Parameters:

Return Value:

The given number encoded as a CBOR object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    PeterO.Numbers.EInteger bigintValue);

Deprecated. Use FromEInteger instead.

Generates a CBOR object from an arbitrary-precision integer.

Parameters:

Return Value:

The given number encoded as a CBOR object. Returns CBORObject.Null if bigintValue is null.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    PeterO.Numbers.ERational bigValue);

Deprecated. Use FromERational instead.

Generates a CBOR object from an arbitrary-precision rational number.

Parameters:

Return Value:

The given number encoded as a CBOR object.

FromObject

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:

Return Value:

A CBORObject object.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    short value);

Deprecated. Use FromInt16 instead.

Generates a CBOR object from a 16-bit signed integer.

Parameters:

Return Value:

A CBOR object generated from the given integer.

FromObject

public static PeterO.Cbor.CBORObject FromObject(
    string strValue);

Deprecated. Use FromString instead.

Generates a CBOR object from a text string.

Parameters:

Return Value:

A CBOR object representing the string, or CBORObject.Null if stringValue is null.

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.

Parameters:

Return Value:

A CBORObject object.

FromObject

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.

Parameters:

Return Value:

A CBORObject object.

FromObject

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.

Parameters:

Return Value:

A CBORObject object.

FromObjectAndTag

public static PeterO.Cbor.CBORObject FromObjectAndTag(
    object valueObValue,
    int smallTag);

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:

Return Value:

A CBOR object where the object valueObValue is given the tag smallTag .

Exceptions:

FromObjectAndTag

public static PeterO.Cbor.CBORObject FromObjectAndTag(
    object valueObValue,
    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:

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:

Return Value:

A CBORObject object.

FromSimpleValue

public static PeterO.Cbor.CBORObject FromSimpleValue(
    int simpleValue);

Creates a CBOR object from a simple value number.

Parameters:

Return Value:

A CBOR object.

Exceptions:

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:

Return Value:

A CBOR object generated from the given number.

FromString

public static PeterO.Cbor.CBORObject FromString(
    string strValue);

Generates a CBOR object from a text string.

Parameters:

Return Value:

A CBOR object representing the string, or CBORObject.Null if stringValue is null.

Exceptions:

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:

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:

Return Value:

A CBORObject object.

FromUShort

public static PeterO.Cbor.CBORObject FromUShort(
    ushort value);

This API is not CLS-compliant.

Converts a 16-bit unsigned integer to a CBOR object.

Parameters:

Return Value:

A CBORObject object.

GetAllTags

public PeterO.Numbers.EInteger[] GetAllTags();

Gets a list of all tags, from outermost to innermost.

Return Value:

An array of tags, or the empty string if this object is untagged.

GetByteString

public byte[] 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. Any changes in the returned array's contents will be reflected in this CBOR object. Note, though, that the array's length can't be changed.

Return Value:

The byte array held by this CBOR object.

Exceptions:

GetHashCode

public override int GetHashCode();

Calculates the hash code of this object. The hash code for a given instance of this class is not guaranteed to be the same across versions of this class, and no application or process IDs are used in the hash code calculation.

Return Value:

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:

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,
    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:

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(
    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:

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

public bool HasMostInnerTag(
    int tagValue);

Returns whether this object has an innermost tag and that tag is of the given number.

Parameters:

Return Value:

true if this object has an innermost tag and that tag is of the given number; otherwise, false .

Exceptions:

HasMostInnerTag

public bool HasMostInnerTag(
    PeterO.Numbers.EInteger bigTagValue);

Returns whether this object has an innermost tag and that tag is of the given number, expressed as an arbitrary-precision number.

Parameters:

Return Value:

true if this object has an innermost tag and that tag is of the given number; otherwise, false .

Exceptions:

HasMostOuterTag

public bool HasMostOuterTag(
    int tagValue);

Returns whether this object has an outermost tag and that tag is of the given number.

Parameters:

Return Value:

true if this object has an outermost tag and that tag is of the given number; otherwise, false .

Exceptions:

HasMostOuterTag

public bool HasMostOuterTag(
    PeterO.Numbers.EInteger bigTagValue);

Returns whether this object has an outermost tag and that tag is of the given number.

Parameters:

Return Value:

true if this object has an outermost tag and that tag is of the given number; otherwise, false .

Exceptions:

HasOneTag

public bool HasOneTag(
    int tagValue);

Returns whether this object has only one tag and that tag is the given number.

Parameters:

Return Value:

true if this object has only one tag and that tag is the given number; otherwise, false .

Exceptions:

HasOneTag

public bool HasOneTag(
    PeterO.Numbers.EInteger bigTagValue);

Returns whether this object has only one tag and that tag is the given number, expressed as an arbitrary-precision integer.

Parameters:

Return Value:

true if this object has only one tag and that tag is the given number; otherwise, false .

Exceptions:

HasOneTag

public bool HasOneTag();

Returns whether this object has only one tag.

Return Value:

true if this object has only one tag; otherwise, false .

HasTag

public bool HasTag(
    int tagValue);

Returns whether this object has a tag of the given number.

Parameters:

Return Value:

true if this object has a tag of the given number; otherwise, false .

Exceptions:

HasTag

public bool HasTag(
    PeterO.Numbers.EInteger bigTagValue);

Returns whether this object has a tag of the given number.

Parameters:

Return Value:

true if this object has a tag of the given number; otherwise, false .

Exceptions:

Insert

public PeterO.Cbor.CBORObject Insert(
    int index,
    object valueOb);

Deprecated. Use the CBORObject overload instead.

Inserts an object at the specified position in this CBOR array.

Parameters:

Return Value:

This instance.

Exceptions:

Insert

public PeterO.Cbor.CBORObject Insert(
    int index,
    PeterO.Cbor.CBORObject cborObj);

Inserts a CBORObject at the specified position in this CBOR array.

Parameters:

Return Value:

This instance.

Exceptions:

NewArray

public static PeterO.Cbor.CBORObject NewArray();

Creates a new empty CBOR array.

Return Value:

A new CBOR array.

NewMap

public static PeterO.Cbor.CBORObject NewMap();

Creates a new empty CBOR map that stores its keys in an undefined order.

Return Value:

A new CBOR map.

NewOrderedMap

public static PeterO.Cbor.CBORObject NewOrderedMap();

Creates a new empty CBOR map that ensures that keys are stored in the order in which they are first inserted.

Return Value:

A new CBOR map.

Operator >

public static bool operator >(
    PeterO.Cbor.CBORObject a,
    PeterO.Cbor.CBORObject b);

Returns whether one object's value is greater than another's.

Parameters:

Return Value:

true if one object's value is greater than another's; otherwise, false .

Exceptions:

Operator >=

public static bool operator >=(
    PeterO.Cbor.CBORObject a,
    PeterO.Cbor.CBORObject b);

Returns whether one object's value is at least another's.

Parameters:

Return Value:

true if one object's value is at least another's; otherwise, false .

Exceptions:

Operator <

public static bool operator <(
    PeterO.Cbor.CBORObject a,
    PeterO.Cbor.CBORObject b);

Returns whether one object's value is less than another's.

Parameters:

Return Value:

true if one object's value is less than another's; otherwise, false .

Exceptions:

Operator <=

public static bool operator <=(
    PeterO.Cbor.CBORObject a,
    PeterO.Cbor.CBORObject b);

Returns whether one object's value is up to another's.

Parameters:

Return Value:

true if one object's value is up to another's; otherwise, false .

Exceptions:

Read

public static PeterO.Cbor.CBORObject Read(
    System.IO.Stream stream);

Reads an object in CBOR format from a data stream. This method will read from the stream until the end of the CBOR object is reached or an error occurs, whichever happens first.

Parameters:

Return Value:

A CBOR object that was read.

Exceptions:

Read

public static PeterO.Cbor.CBORObject Read(
    System.IO.Stream stream,
    PeterO.Cbor.CBOREncodeOptions options);

Reads an object in CBOR format from a data stream, using the specified options to control the decoding process. This method will read from the stream until the end of the CBOR object is reached or an error occurs, whichever happens first.

Parameters:

Return Value:

A CBOR object that was read.

Exceptions:

ReadJSON

public static PeterO.Cbor.CBORObject ReadJSON(
    System.IO.Stream stream);

Generates a CBOR object from a data stream in JavaScript Object Notation (JSON) format. 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.). (This behavior may change to supporting only UTF-8, with or without a byte order mark, in version 5.0 or later, perhaps with an option to restore the previous behavior of also supporting UTF-16 and UTF-32.).

Parameters:

Return Value:

A CBOR object.

Exceptions:

ReadJSON

public static PeterO.Cbor.CBORObject ReadJSON(
    System.IO.Stream stream,
    PeterO.Cbor.JSONOptions jsonoptions);

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.). (This behavior may change to supporting only UTF-8, with or without a byte order mark, in version 5.0 or later, perhaps with an option to restore the previous behavior of also supporting UTF-16 and UTF-32.).

Parameters:

Return Value:

A CBOR object containing the JSON data decoded.

Exceptions:

ReadJSONSequence

public static PeterO.Cbor.CBORObject[] ReadJSONSequence(
    System.IO.Stream stream);

Generates a list of CBOR objects from a data stream in JavaScript Object Notation (JSON) text sequence format (RFC 7464). The data stream must be in UTF-8 encoding and may not begin with a byte-order mark (U+FEFF).

Generally, each JSON text in a JSON text sequence is written as follows: Write a record separator byte (0x1e), then write the JSON text in UTF-8 (without a byte order mark, U+FEFF), then write the line feed byte (0x0a). RFC 7464, however, uses a more liberal syntax for parsing JSON text sequences.

Parameters:

Return Value:

A list of CBOR objects read from the JSON sequence. Objects that could not be parsed are replaced with null (as opposed to CBORObject.Null ) in the given list.

Exceptions:

ReadJSONSequence

public static PeterO.Cbor.CBORObject[] ReadJSONSequence(
    System.IO.Stream stream,
    PeterO.Cbor.JSONOptions jsonoptions);

Generates a list of CBOR objects from a data stream in JavaScript Object Notation (JSON) text sequence format (RFC 7464). The data stream must be in UTF-8 encoding and may not begin with a byte-order mark (U+FEFF).

Generally, each JSON text in a JSON text sequence is written as follows: Write a record separator byte (0x1e), then write the JSON text in UTF-8 (without a byte order mark, U+FEFF), then write the line feed byte (0x0a). RFC 7464, however, uses a more liberal syntax for parsing JSON text sequences.

Parameters:

Return Value:

A list of CBOR objects read from the JSON sequence. Objects that could not be parsed are replaced with null (as opposed to CBORObject.Null ) in the given list.

Exceptions:

ReadSequence

public static PeterO.Cbor.CBORObject[] ReadSequence(
    System.IO.Stream stream);

Reads a sequence of objects in CBOR format from a data stream. This method will read CBOR objects from the stream until the end of the stream is reached or an error occurs, whichever happens first.

Parameters:

Return Value:

An array containing the CBOR objects that were read from the data stream. Returns an empty array if there is no unread data in the stream.

Exceptions:

ReadSequence

public static PeterO.Cbor.CBORObject[] ReadSequence(
    System.IO.Stream stream,
    PeterO.Cbor.CBOREncodeOptions options);

Reads a sequence of objects in CBOR format from a data stream. This method will read CBOR objects from the stream until the end of the stream is reached or an error occurs, whichever happens first.

Parameters:

Return Value:

An array containing the CBOR objects that were read from the data stream. Returns an empty array if there is no unread data in the stream.

Exceptions:

Remove

public bool Remove(
    object obj);

If this object is an array, removes the first instance of the specified item (once converted to a CBOR object) from the array. If this object is a map, removes the item with the given key (once converted to a CBOR object) from the map.

Parameters:

Return Value:

true if the item was removed; otherwise, false .

Exceptions:

Remove

public bool Remove(
    PeterO.Cbor.CBORObject obj);

If this object is an array, removes the first instance of the specified item from the array. If this object is a map, removes the item with the given key from the map.

Parameters:

Return Value:

true if the item was removed; otherwise, false .

Exceptions:

RemoveAt

public bool RemoveAt(
    int index);

Removes the item at the given index of this CBOR array.

Parameters:

Return Value:

Returns "true" if the object was removed. Returns "false" if the given index is less than 0, or is at least as high as the number of items in the array.

Exceptions:

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:

Return Value:

This instance.

Exceptions:

Set

public PeterO.Cbor.CBORObject Set(
    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:

Return Value:

This instance.

Exceptions:

Set

public PeterO.Cbor.CBORObject Set(
    PeterO.Cbor.CBORObject mapKey,
    PeterO.Cbor.CBORObject mapValue);

Maps an object to a key in this CBOR map, or adds the value if the key doesn't exist.

Parameters:

Return Value:

This instance.

Exceptions:

ToJSONBytes

public byte[] ToJSONBytes(
    PeterO.Cbor.JSONOptions jsonoptions);

Converts this object to a byte array in JavaScript Object Notation (JSON) format. The JSON text will be written out in UTF-8 encoding, without a byte order mark, to the byte array. See the overload to ToJSONString taking a JSONOptions argument for further information.

Parameters:

Return Value:

A byte array containing the converted object in JSON format.

Exceptions:

ToJSONBytes

public byte[] ToJSONBytes();

Converts this object to a byte array in JavaScript Object Notation (JSON) format. The JSON text will be written out in UTF-8 encoding, without a byte order mark, to the byte array. See the overload to ToJSONString taking a JSONOptions argument for further information.

Return Value:

A byte array containing the converted in JSON format.

ToJSONString

public string ToJSONString(
    PeterO.Cbor.JSONOptions options);

Converts this object to a text string in JavaScript Object Notation (JSON) format, using the specified options to control the encoding process. This function works not only with arrays and maps, but also integers, strings, byte arrays, and other JSON data types. Notes:

Warning: In general, if this CBOR object contains integer map keys or uses other features not supported in JSON, and the application converts this CBOR object to JSON and back to CBOR, the application should not expect the new CBOR object to be exactly the same as the original. This is because the conversion in many cases may have to convert unsupported features in JSON to supported features which correspond to a different feature in CBOR (such as converting integer map keys, which are supported in CBOR but not JSON, to text strings, which are supported in both).

The example code given below (originally written in C# for the.NET version) can be used to write out certain keys of a CBOR map in a given order to a JSON string.

/* Generates a JSON string of 'mapObj' whose keys are in the order
             given
             in 'keys' . Only keys found in 'keys' will be written if they exist in
             'mapObj'. */ private static string KeysToJSONMap(CBORObject mapObj,
             IList<CBORObject> keys) { if (mapObj == null) { throw new
             ArgumentNullException)nameof(mapObj));}
             if (keys == null) { throw new
             ArgumentNullException)nameof(keys));}
             if (obj.Type != CBORType.Map) {
             throw new ArgumentException("'obj' is not a map."); } StringBuilder
             builder = new StringBuilder(); var first = true; builder.Append("{");
             for (CBORObject key in keys) { if (mapObj.ContainsKey(key)) { if
             (!first) {builder.Append(", ");} var keyString=(key.CBORType ==
             CBORType.String) ? key.AsString() : key.ToJSONString();
             builder.Append(CBORObject.FromObject(keyString) .ToJSONString())
             .Append(":").Append(mapObj[key].ToJSONString()); first=false; } } return
             builder.Append("}").ToString(); }

.

Parameters:

Return Value:

A text string containing the converted object in JSON format.

Exceptions:

ToJSONString

public string ToJSONString();

Converts this object to a text string in JavaScript Object Notation (JSON) format. See the overload to ToJSONString taking a JSONOptions argument for further information. If the CBOR object contains CBOR maps, or is a CBOR map itself, the order in which the keys to the map are written out to the JSON string is undefined unless the map was created using the NewOrderedMap method. Map keys other than untagged text strings are converted to JSON strings before writing them out (for example, 22("Test") is converted to "Test" and true is converted to "true" ). After such conversion, if two or more keys for the same map are identical, this method throws a CBORException. The example code given in PeterO.Cbor.CBORObject.ToJSONString(PeterO.Cbor.JSONOptions) can be used to write out certain keys of a CBOR map in a given order to a JSON string, or to write out a CBOR object as part of a JSON text sequence.

Warning: In general, if this CBOR object contains integer map keys or uses other features not supported in JSON, and the application converts this CBOR object to JSON and back to CBOR, the application should not expect the new CBOR object to be exactly the same as the original. This is because the conversion in many cases may have to convert unsupported features in JSON to supported features which correspond to a different feature in CBOR (such as converting integer map keys, which are supported in CBOR but not JSON, to text strings, which are supported in both).

Return Value:

A text string containing the converted object in JSON format.

ToObject

public object ToObject(
    System.Type t);

Converts this CBOR object to an object of an arbitrary type. See the documentation for the overload of this method taking a CBORTypeMapper parameter for more information. This method doesn't use a CBORTypeMapper parameter to restrict which data types are eligible for Plain-Old-Data serialization.

Java offers no easy way to express a generic type, at least none as easy as C#'s typeof operator. The following example, written in Java, is a way to specify that the return value will be an ArrayList of String objects.

Type arrayListString = new ParameterizedType() { public Type[]
            getActualTypeArguments() { /* Contains one type parameter,
            String*/
            return new Type[] { String.class }; }
            public Type getRawType() { /* Raw type is
            ArrayList */ return ArrayList.class; }
            public Type getOwnerType() {
            return null; } };
            ArrayList<String> array = (ArrayList<String>)
            cborArray.ToObject(arrayListString);

By comparison, the C# version is much shorter.

var array = (List<String>)cborArray.ToObject(
            typeof(List<String>));

.

Parameters:

Return Value:

The converted object.

Exceptions:

ToObject

public object ToObject(
    System.Type t,
    PeterO.Cbor.CBORTypeMapper mapper);

Converts this CBOR object to an object of an arbitrary type. See the documentation for the overload of this method taking a CBORTypeMapper and PODOptions parameters parameters for more information.

Parameters:

Return Value:

The converted object.

Exceptions:

ToObject

public object ToObject(
    System.Type t,
    PeterO.Cbor.CBORTypeMapper mapper,
    PeterO.Cbor.PODOptions options);

Converts this CBOR object to an object of an arbitrary type. The following cases are checked in the logical order given (rather than the strict order in which they are implemented by this library):

The following example (originally written in C# for the DotNet version) uses a CBORTypeMapper to change how CBOR objects are converted to DateTime objects. In this case, the ToObject method assumes the CBOR object is an untagged number giving the number of seconds since the start of 1970.

var conv = new CBORTypeMapper().AddConverter(typeof(DateTime),
            CBORDateConverter.UntaggedNumber);
            var obj = CBORObject.FromObject().ToObject<DateTime>(conv);

Java offers no easy way to express a generic type, at least none as easy as C#'s typeof operator. The following example, written in Java, is a way to specify that the return value will be an ArrayList of String objects.

Type arrayListString = new ParameterizedType() { public Type[]
            getActualTypeArguments() { /* Contains one type parameter,
            String*/
            return new Type[] { String.class }; }
            public Type getRawType() { /* Raw type is
            ArrayList */ return ArrayList.class; } public Type getOwnerType() {
            return null; } }; ArrayList<String> array =
            (ArrayList<String>) cborArray.ToObject(arrayListString);

By comparison, the C# version is much shorter.

var array = (List<String>)cborArray.ToObject(
            typeof(List<String>));

.

Parameters:

Return Value:

The converted object.

Exceptions:

ToObject

public object ToObject(
    System.Type t,
    PeterO.Cbor.PODOptions options);

Converts this CBOR object to an object of an arbitrary type. See the documentation for the overload of this method taking a CBORTypeMapper and PODOptions parameters for more information. This method (without a CBORTypeMapper parameter) allows all data types not otherwise handled to be eligible for Plain-Old-Data serialization.

Parameters:

Return Value:

The converted object.

Exceptions:

ToObject

public T ToObject<T>(
    PeterO.Cbor.CBORTypeMapper mapper);

Converts this CBOR object to an object of an arbitrary type. See M:PeterO.Cbor.CBORObject.ToObject(System.Type) for further information.

Parameters:

Return Value:

The converted object.

Exceptions:

ToObject

public T ToObject<T>(
    PeterO.Cbor.CBORTypeMapper mapper,
    PeterO.Cbor.PODOptions options);

Converts this CBOR object to an object of an arbitrary type. See M:PeterO.Cbor.CBORObject.ToObject(System.Type) for further information.

Parameters:

Return Value:

The converted object.

Exceptions:

ToObject

public T ToObject<T>(
    PeterO.Cbor.PODOptions options);

Converts this CBOR object to an object of an arbitrary type. See M:PeterO.Cbor.CBORObject.ToObject(System.Type) for further information.

Parameters:

Return Value:

The converted object.

Exceptions:

ToObject

public T ToObject<T>();

Converts this CBOR object to an object of an arbitrary type. See M:PeterO.Cbor.CBORObject.ToObject(System.Type) for further information.

Parameters:

Return Value:

The converted object.

Exceptions:

ToString

public override string ToString();

Returns this CBOR object in a text form intended to be read by humans. The value returned by this method is not intended to be parsed by computer programs, and the exact text of the value may change at any time between versions of this library. The returned string is not necessarily in JavaScript Object Notation (JSON); to convert CBOR objects to JSON strings, use the PeterO.Cbor.CBORObject.ToJSONString(PeterO.Cbor.JSONOptions) method instead.

Return Value:

A text representation of this object.

Untag

public PeterO.Cbor.CBORObject Untag();

Gets an object with the same value as this one but without the tags it has, if any. If this object is an array, map, or byte string, the data will not be copied to the returned object, so changes to the returned object will be reflected in this one.

Return Value:

A CBOR object.

UntagOne

public PeterO.Cbor.CBORObject UntagOne();

Gets an object with the same value as this one but without this object's outermost tag, if any. If this object is an array, map, or byte string, the data will not be copied to the returned object, so changes to the returned object will be reflected in this one.

Return Value:

A CBOR object.

WithTag

public PeterO.Cbor.CBORObject WithTag(
    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:

Return Value:

A CBOR object with the same value as this one but given the tag smallTag in addition to its existing tags (the new tag is made the outermost tag).

Exceptions:

WithTag

public PeterO.Cbor.CBORObject WithTag(
    PeterO.Numbers.EInteger bigintTag);

Generates a CBOR object from this one, but gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag).

Parameters:

Return Value:

A CBOR object with the same value as this one but given the tag bigintTag in addition to its existing tags (the new tag is made the outermost tag).

Exceptions:

WithTag

public PeterO.Cbor.CBORObject WithTag(
    ulong tag);

This API is not CLS-compliant.

Generates a CBOR object from this one, but gives the resulting object a tag in addition to its existing tags (the new tag is made the outermost tag).

Parameters:

Return Value:

A CBOR object with the same value as this one but given the tag tag in addition to its existing tags (the new tag is made the outermost tag).

Write

public static void Write(
    bool value,
    System.IO.Stream stream);

Writes a Boolean value in CBOR format to a data stream.

Parameters:

Exceptions:

Write

public static void Write(
    byte value,
    System.IO.Stream stream);

Writes a byte (0 to 255) in CBOR format to a data stream. If the value is less than 24, writes that byte. If the value is 25 to 255, writes the byte 24, then this byte's value.

Parameters:

Exceptions:

Write

public static void Write(
    double value,
    System.IO.Stream stream);

Writes a 64-bit floating-point number in CBOR format to a data stream. The number is written using the shortest floating-point encoding possible; this is a change from previous versions.

Parameters:

Exceptions:

Write

public static void Write(
    float value,
    System.IO.Stream stream);

Writes a 32-bit floating-point number in CBOR format to a data stream. The number is written using the shortest floating-point encoding possible; this is a change from previous versions.

Parameters:

Exceptions:

Write

public static void Write(
    int value,
    System.IO.Stream stream);

Writes a 32-bit signed integer in CBOR format to a data stream.

Parameters:

Exceptions:

Write

public static void Write(
    long value,
    System.IO.Stream stream);

Writes a 64-bit signed integer in CBOR format to a data stream.

Parameters:

Exceptions:

Write

public static void Write(
    object objValue,
    System.IO.Stream output,
    PeterO.Cbor.CBOREncodeOptions options);

Writes an arbitrary object to a CBOR data stream, using the specified options for controlling how the object is encoded to CBOR data format. If the object is convertible to a CBOR map or a CBOR object that contains CBOR maps, the order in which the keys to those maps are written out to the data stream is undefined unless the map was created using the NewOrderedMap method. The example code given in M:PeterO.Cbor.CBORObject.WriteTo(System.IO.Stream) can be used to write out certain keys of a CBOR map in a given order. Currently, the following objects are supported:

Parameters:

.

Exceptions:

Write

public static void Write(
    object objValue,
    System.IO.Stream stream);

Writes a CBOR object to a CBOR data stream. See the three-parameter Write method that takes a CBOREncodeOptions.

Parameters:

Write

public static void Write(
    PeterO.Cbor.CBORObject value,
    System.IO.Stream stream);

Writes a CBOR object to a CBOR data stream.

Parameters:

Exceptions:

Write

public static void Write(
    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.

Parameters:

Exceptions:

Write

public static void Write(
    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.

Parameters:

Exceptions:

Write

public static void Write(
    PeterO.Numbers.EInteger bigint,
    System.IO.Stream stream);

Writes a arbitrary-precision integer in CBOR format to a data stream.

Parameters:

Exceptions:

Write

public static void Write(
    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.

Parameters:

Exceptions:

Write

public static void Write(
    sbyte value,
    System.IO.Stream stream);

This API is not CLS-compliant.

Writes an 8-bit signed integer in CBOR format to a data stream.

Parameters:

Write

public static void Write(
    short value,
    System.IO.Stream stream);

Writes a 16-bit signed integer in CBOR format to a data stream.

Parameters:

Exceptions:

Write

public static void Write(
    string str,
    System.IO.Stream stream);

Writes a text string in CBOR format to a data stream. The string will be encoded using definite-length encoding regardless of its length.

Parameters:

Exceptions:

Write

public static void Write(
    string str,
    System.IO.Stream stream,
    PeterO.Cbor.CBOREncodeOptions options);

Writes a text string in CBOR format to a data stream, using the given options to control the encoding process.

Parameters:

Exceptions:

Write

public static void Write(
    uint value,
    System.IO.Stream stream);

This API is not CLS-compliant.

Writes a 32-bit unsigned integer in CBOR format to a data stream.

Parameters:

Write

public static void Write(
    ulong value,
    System.IO.Stream stream);

This API is not CLS-compliant.

Writes a 64-bit unsigned integer in CBOR format to a data stream.

Parameters:

Exceptions:

Write

public static void Write(
    ushort value,
    System.IO.Stream stream);

This API is not CLS-compliant.

Writes a 16-bit unsigned integer in CBOR format to a data stream.

Parameters:

WriteFloatingPointBits

public static int WriteFloatingPointBits(
    System.IO.Stream outputStream,
    long floatingBits,
    int byteCount);

Writes the bits of a floating-point number in CBOR format to a data stream.

Parameters:

Return Value:

The number of 8-bit bytes ordered to be written to the data stream.

Exceptions:

WriteFloatingPointBits

public static int WriteFloatingPointBits(
    System.IO.Stream outputStream,
    long floatingBits,
    int byteCount,
    bool shortestForm);

Writes the bits of a floating-point number in CBOR format to a data stream.

Parameters:

Return Value:

The number of 8-bit bytes ordered to be written to the data stream.

Exceptions:

WriteFloatingPointValue

public static int WriteFloatingPointValue(
    System.IO.Stream outputStream,
    double doubleVal,
    int byteCount);

Writes a 64-bit binary floating-point number in CBOR format to a data stream, either in its 64-bit form, or its rounded 32-bit or 16-bit equivalent.

Parameters:

Return Value:

The number of 8-bit bytes ordered to be written to the data stream.

Exceptions:

WriteFloatingPointValue

public static int WriteFloatingPointValue(
    System.IO.Stream outputStream,
    float singleVal,
    int byteCount);

Writes a 32-bit binary floating-point number in CBOR format to a data stream, either in its 64- or 32-bit form, or its rounded 16-bit equivalent.

Parameters:

Return Value:

The number of 8-bit bytes ordered to be written to the data stream.

Exceptions:

WriteJSON

public static void WriteJSON(
    object obj,
    System.IO.Stream outputStream);

Converts an arbitrary object to a text string in JavaScript Object Notation (JSON) format, as in the ToJSONString method, and writes that string to a data stream in UTF-8. If the object is convertible to a CBOR map, or to a CBOR object that contains CBOR maps, the order in which the keys to those maps are written out to the JSON string is undefined unless the map was created using the NewOrderedMap method. The example code given in PeterO.Cbor.CBORObject.ToJSONString(PeterO.Cbor.JSONOptions) can be used to write out certain keys of a CBOR map in a given order to a JSON string.

Parameters:

.

Exceptions:

WriteJSONTo

public void WriteJSONTo(
    System.IO.Stream outputStream);

Converts this object to a text string in JavaScript Object Notation (JSON) format, as in the ToJSONString method, and writes that string to a data stream in UTF-8. If the CBOR object contains CBOR maps, or is a CBOR map, the order in which the keys to the map are written out to the JSON string is undefined unless the map was created using the NewOrderedMap method. The example code given in PeterO.Cbor.CBORObject.ToJSONString(PeterO.Cbor.JSONOptions) can be used to write out certain keys of a CBOR map in a given order to a JSON string.

The following example (originally written in C# for the.NET version) writes out a CBOR object as part of a JSON text sequence (RFC 7464).

            stream.WriteByte(0x1e); /* RS */
            cborObject.WriteJSONTo(stream); /* JSON */
            stream.WriteByte(0x0a); /* LF */

The following example (originally written in C# for the.NET version) shows how to use the LimitedMemoryStream class (implemented in LimitedMemoryStream.cs in the peteroupc/CBOR open-source repository) to limit the size of supported JSON serializations of CBOR objects.

            /* maximum supported JSON size in bytes*/
            var maxSize = 20000;
            using (var ms = new LimitedMemoryStream(maxSize)) {
            cborObject.WriteJSONTo(ms);
            var bytes = ms.ToArray();
            }

The following example (written in Java for the Java version) shows how to use a subclassed OutputStream together with a ByteArrayOutputStream to limit the size of supported JSON serializations of CBOR objects.

            /* maximum supported JSON size in bytes*/
            final int maxSize = 20000;
            ByteArrayOutputStream ba = new ByteArrayOutputStream();
            /* throws UnsupportedOperationException if too big*/
            cborObject.WriteJSONTo(new FilterOutputStream(ba) {
            private int size = 0;
            public void write(byte[] b, int off, int len) throws IOException {
            if (len>(maxSize-size)) {
            throw new UnsupportedOperationException();
            }
            size+=len; out.write(b, off, len);
            }
            public void write(byte b) throws IOException {
            if (size >= maxSize) {
            throw new UnsupportedOperationException();
            }
            size++; out.write(b);
            }
            });
            byte[] bytes = ba.toByteArray();

The following example (originally written in C# for the.NET version) shows how to use a.NET MemoryStream to limit the size of supported JSON serializations of CBOR objects. The disadvantage is that the extra memory needed to do so can be wasteful, especially if the average serialized object is much smaller than the maximum size given (for example, if the maximum size is 20000 bytes, but the average serialized object has a size of 50 bytes).

            var backing = new byte[20000]; /* maximum supported JSON size in
            bytes*/
            byte[] bytes1, bytes2;
            using (var ms = new MemoryStream(backing)) {
            /* throws NotSupportedException if too big*/
            cborObject.WriteJSONTo(ms);
            bytes1 = new byte[ms.Position];
            /* Copy serialized data if successful*/
            System.ArrayCopy(backing, 0, bytes1, 0, (int)ms.Position);
            /* Reset memory stream*/
            ms.Position = 0;
            cborObject2.WriteJSONTo(ms);
            bytes2 = new byte[ms.Position];
            /* Copy serialized data if successful*/
            System.ArrayCopy(backing, 0, bytes2, 0, (int)ms.Position);
            }

Parameters:

Exceptions:

WriteJSONTo

public void WriteJSONTo(
    System.IO.Stream outputStream,
    PeterO.Cbor.JSONOptions options);

Converts this object to a text string in JavaScript Object Notation (JSON) format, as in the ToJSONString method, and writes that string to a data stream in UTF-8, using the given JSON options to control the encoding process. If the CBOR object contains CBOR maps, or is a CBOR map, the order in which the keys to the map are written out to the JSON string is undefined unless the map was created using the NewOrderedMap method. The example code given in PeterO.Cbor.CBORObject.ToJSONString(PeterO.Cbor.JSONOptions) can be used to write out certain keys of a CBOR map in a given order to a JSON string.

Parameters:

Exceptions:

WriteTo

public void WriteTo(
    System.IO.Stream stream);

Writes this CBOR object to a data stream. If the CBOR object contains CBOR maps, or is a CBOR map, the order in which the keys to the map are written out to the data stream is undefined unless the map was created using the NewOrderedMap method. See the examples (originally written in C# for the.NET version) for ways to write out certain keys of a CBOR map in a given order. In the case of CBOR objects of type FloatingPoint, the number is written using the shortest floating-point encoding possible; this is a change from previous versions.

The following example shows a method that writes each key of 'mapObj' to 'outputStream', in the order given in 'keys', where 'mapObj' is written out in the form of a CBOR definite-length map . Only keys found in 'keys' will be written if they exist in 'mapObj'.

private static void WriteKeysToMap(CBORObject mapObj,
            IList<CBORObject> keys, Stream outputStream) {
            if (mapObj == null) {
            throw new ArgumentNullException(nameof(mapObj));}
            if (keys == null)
            {throw new ArgumentNullException(nameof(keys));}
            if (outputStream ==
            null) {throw new ArgumentNullException(nameof(outputStream));}
            if
            (obj.Type!=CBORType.Map) { throw new ArgumentException("'obj' is not a
            map."); } int keyCount = 0; for (CBORObject key in keys) { if
            (mapObj.ContainsKey(key)) { keyCount++; } }
            CBORObject.WriteValue(outputStream, 5, keyCount); for (CBORObject key in
            keys) { if (mapObj.ContainsKey(key)) { key.WriteTo(outputStream);
            mapObj[key].WriteTo(outputStream); } } }

The following example shows a method that writes each key of 'mapObj' to 'outputStream', in the order given in 'keys', where 'mapObj' is written out in the form of a CBOR indefinite-length map . Only keys found in 'keys' will be written if they exist in 'mapObj'.

private static void WriteKeysToIndefMap(CBORObject mapObj,
            IList<CBORObject> keys, Stream outputStream) { if (mapObj == null)
            { throw new ArgumentNullException(nameof(mapObj));}
            if (keys == null)
            {throw new ArgumentNullException(nameof(keys));}
            if (outputStream ==
            null) {throw new ArgumentNullException(nameof(outputStream));}
            if
            (obj.Type!=CBORType.Map) { throw new ArgumentException("'obj' is not a
            map."); } outputStream.WriteByte((byte)0xBF); for (CBORObject key in
            keys) { if (mapObj.ContainsKey(key)) { key.WriteTo(outputStream);
            mapObj[key].WriteTo(outputStream); } }
            outputStream.WriteByte((byte)0xff); }

The following example shows a method that writes out a list of objects to 'outputStream' as an indefinite-length CBOR array .

private static void WriteToIndefArray(IList<object> list,
            Stream
            outputStream) { if (list == null) { throw new
            ArgumentNullException(nameof(list));}
            if (outputStream == null) {throw
            new ArgumentNullException(nameof(outputStream));}
            outputStream.WriteByte((byte)0x9f); for (object item in list) { new
            CBORObject(item).WriteTo(outputStream); }
            outputStream.WriteByte((byte)0xff); }

The following example (originally written in C# for the.NET version) shows how to use the LimitedMemoryStream class (implemented in LimitedMemoryStream.cs in the peteroupc/CBOR open-source repository) to limit the size of supported CBOR serializations.

            /* maximum supported CBOR size in bytes*/
            var maxSize = 20000;
            using (var ms = new LimitedMemoryStream(maxSize)) {
            cborObject.WriteTo(ms);
            var bytes = ms.ToArray();
            }

The following example (written in Java for the Java version) shows how to use a subclassed OutputStream together with a ByteArrayOutputStream to limit the size of supported CBOR serializations.

            /* maximum supported CBOR size in bytes*/
            final int maxSize = 20000;
            ByteArrayOutputStream ba = new ByteArrayOutputStream();
            /* throws UnsupportedOperationException if too big*/
            cborObject.WriteTo(new FilterOutputStream(ba) {
            private int size = 0;
            public void write(byte[] b, int off, int len) throws IOException {
            if (len>(maxSize-size)) {
            throw new UnsupportedOperationException();
            }
            size+=len; out.write(b, off, len);
            }
            public void write(byte b) throws IOException {
            if (size >= maxSize) {
            throw new UnsupportedOperationException();
            }
            size++; out.write(b);
            }
            });
            byte[] bytes = ba.toByteArray();

The following example (originally written in C# for the.NET version) shows how to use a.NET MemoryStream to limit the size of supported CBOR serializations. The disadvantage is that the extra memory needed to do so can be wasteful, especially if the average serialized object is much smaller than the maximum size given (for example, if the maximum size is 20000 bytes, but the average serialized object has a size of 50 bytes).

            var backing = new byte[20000]; /* maximum supported CBOR size in
            bytes*/
            byte[] bytes1, bytes2;
            using (var ms = new MemoryStream(backing)) {
            /* throws NotSupportedException if too big*/
            cborObject.WriteTo(ms);
            bytes1 = new byte[ms.Position];
            /* Copy serialized data if successful*/
            System.ArrayCopy(backing, 0, bytes1, 0, (int)ms.Position);
            /* Reset memory stream*/
            ms.Position = 0;
            cborObject2.WriteTo(ms);
            bytes2 = new byte[ms.Position];
            /* Copy serialized data if successful*/
            System.ArrayCopy(backing, 0, bytes2, 0, (int)ms.Position);
            }

Parameters:

Exceptions:

WriteTo

public void WriteTo(
    System.IO.Stream stream,
    PeterO.Cbor.CBOREncodeOptions options);

Writes this CBOR object to a data stream, using the specified options for encoding the data to CBOR format. If the CBOR object contains CBOR maps, or is a CBOR map, the order in which the keys to the map are written out to the data stream is undefined unless the map was created using the NewOrderedMap method. The example code given in M:PeterO.Cbor.CBORObject.WriteTo(System.IO.Stream) can be used to write out certain keys of a CBOR map in a given order. In the case of CBOR objects of type FloatingPoint, the number is written using the shortest floating-point encoding possible; this is a change from previous versions.

Parameters:

Exceptions:

WriteValue

public static int WriteValue(
    System.IO.Stream outputStream,
    int majorType,
    int value);

Writes a CBOR major type number and an integer 0 or greater associated with it to a data stream, where that integer is passed to this method as a 32-bit signed integer. This is a low-level method that is useful for implementing custom CBOR encoding methodologies. This method encodes the given major type and value in the shortest form allowed for the major type.

There are other useful things to note when encoding CBOR that are not covered by this WriteValue method. To mark the start of an indefinite-length array, write the 8-bit byte 0x9f to the output stream. To mark the start of an indefinite-length map, write the 8-bit byte 0xbf to the output stream. To mark the end of an indefinite-length array or map, write the 8-bit byte 0xff to the output stream.

In the following example, an array of three objects is written as CBOR to a data stream.

/* array, length 3*/
            CBORObject.WriteValue(stream, 4, 3);
            /* item 1 */
            CBORObject.Write("hello world", stream);
            CBORObject.Write(25, stream); /* item 2*/
            CBORObject.Write(false, stream); /* item 3*/

In the following example, a map consisting of two key-value pairs is written as CBOR to a data stream.

CBORObject.WriteValue(stream, 5, 2); /* map, 2
            pairs*/
            CBORObject.Write("number", stream); /* key 1 */
            CBORObject.Write(25, stream); /* value 1 */
            CBORObject.Write("string", stream); /* key 2*/
            CBORObject.Write("hello", stream); /* value 2*/

In the following example (originally written in C# for the.NET Framework version), a text string is written as CBOR to a data stream.

string str = "hello world"; byte[] bytes =
            DataUtilities.GetUtf8Bytes(str, true); CBORObject.WriteValue(stream, 4,
            bytes.Length); stream.Write(bytes, 0, bytes.Length);

.

Parameters:

Return Value:

The number of bytes ordered to be written to the data stream.

Exceptions:

WriteValue

public static int WriteValue(
    System.IO.Stream outputStream,
    int majorType,
    long value);

Writes a CBOR major type number and an integer 0 or greater associated with it to a data stream, where that integer is passed to this method as a 64-bit signed integer. This is a low-level method that is useful for implementing custom CBOR encoding methodologies. This method encodes the given major type and value in the shortest form allowed for the major type.

There are other useful things to note when encoding CBOR that are not covered by this WriteValue method. To mark the start of an indefinite-length array, write the 8-bit byte 0x9f to the output stream. To mark the start of an indefinite-length map, write the 8-bit byte 0xbf to the output stream. To mark the end of an indefinite-length array or map, write the 8-bit byte 0xff to the output stream. For examples, see the WriteValue(Stream, int, int) overload.

Parameters:

Return Value:

The number of bytes ordered to be written to the data stream.

Exceptions:

WriteValue

public static int WriteValue(
    System.IO.Stream outputStream,
    int majorType,
    PeterO.Numbers.EInteger bigintValue);

Writes a CBOR major type number and an integer 0 or greater associated with it to a data stream, where that integer is passed to this method as an arbitrary-precision integer. This is a low-level method that is useful for implementing custom CBOR encoding methodologies. This method encodes the given major type and value in the shortest form allowed for the major type.

There are other useful things to note when encoding CBOR that are not covered by this WriteValue method. To mark the start of an indefinite-length array, write the 8-bit byte 0x9f to the output stream. To mark the start of an indefinite-length map, write the 8-bit byte 0xbf to the output stream. To mark the end of an indefinite-length array or map, write the 8-bit byte 0xff to the output stream.

Parameters:

Return Value:

The number of bytes ordered to be written to the data stream.

Exceptions:

WriteValue

public static int WriteValue(
    System.IO.Stream outputStream,
    int majorType,
    uint value);

This API is not CLS-compliant.

Writes a CBOR major type number and an integer 0 or greater associated with it to a data stream, where that integer is passed to this method as a 32-bit unsigned integer. This is a low-level method that is useful for implementing custom CBOR encoding methodologies. This method encodes the given major type and value in the shortest form allowed for the major type.

Parameters:

Return Value:

The number of bytes ordered to be written to the data stream.

Exceptions:

WriteValue

public static int WriteValue(
    System.IO.Stream outputStream,
    int majorType,
    ulong value);

This API is not CLS-compliant.

Writes a CBOR major type number and an integer 0 or greater associated with it to a data stream, where that integer is passed to this method as a 64-bit unsigned integer. This is a low-level method that is useful for implementing custom CBOR encoding methodologies. This method encodes the given major type and value in the shortest form allowed for the major type.

Parameters:

Return Value:

The number of bytes ordered to be written to the data stream.

Exceptions:

Back to CBOR start page.