Struct cbor_data::Cbor

pub struct Cbor(/* private fields */);

Wrapper around a byte slice that encodes a valid CBOR item.

For details on the format see RFC 8949.

When interpreting CBOR messages from the outside (e.g. from the network) it is advisable to ingest those using the CborOwned::canonical constructor. In case the message was encoded for example using CborBuilder it is sufficient to use the unchecked constructor.

The Display implementation adheres to the diagnostic notation.

Implementations

impl Cbor

pub fn unchecked(bytes: &[u8]) -> &Self

Unconditionally cast the given byte slice as CBOR item

No checks on the integrity are made, indexing methods may panic if encoded lengths are out of bound or when encountering invalid encodings. If you want to carefully treat data obtained from unreliable sources, prefer CborOwned::canonical.

The results of CborBuilder can safely be fed to this method.

pub fn from_cow_unchecked(bytes: Cow<'_, [u8]>) -> Cow<'_, Cbor>

Unconditionally convert the given bytes as CBOR item

The borrowed variant is converted using unchecked without allocating. The owned variant is converted by either reusing the allocated vector or storing the bytes inline (if they fit) and releasing the vector.

No checks on the integrity are made, indexing methods may panic if encoded lengths are out of bound or when encountering invalid encodings. If you want to carefully treat data obtained from unreliable sources, prefer CborOwned::canonical.

pub fn checked(bytes: &[u8]) -> Result<&Self, ParseError>

Cast the given byte slice as CBOR item if the encoding is valid

pub fn checked_prefix(bytes: &[u8]) -> Result<(&Self, &[u8]), ParseError>

Cast the given byte slice as CBOR item if the encoding is valid, permitting more bytes to follow the item

pub fn from_cow_checked( bytes: Cow<'_, [u8]> ) -> Result<Cow<'_, Cbor>, ParseError>

Convert the given bytes to a CBOR item if the encoding is valid

The borrowed variant is converted using checked without allocating. The owned variant is converted using CborOwned::canonical.

pub fn as_slice(&self) -> &[u8]

A view onto the underlying bytes

pub fn decode(&self) -> CborValue<'_>

Interpret the CBOR item at a higher level

While kind gives you precise information on how the item is encoded, this method interprets the tag-based encoding according to the standard, adding for example big integers, decimals, and floats, or turning base64-encoded text strings into binary strings.

pub fn tags(&self) -> Tags<'_>

An iterator over the tags present on this item, from outermost to innermost

pub fn kind(&self) -> ItemKind<'_>

The low-level encoding of this item, without its tags

pub fn tagged_item(&self) -> TaggedItem<'_>

The low-level encoding of this item with its tags

pub fn try_null(&self) -> Result<(), TypeError>

More efficient shortcut for .decode().is_null() with error reporting.

pub fn try_bool(&self) -> Result<bool, TypeError>

More efficient shortcut for .decode().as_bool() with error reporting.

pub fn try_number(&self) -> Result<Number<'_>, TypeError>

More efficient shortcut for .decode().to_number() with error reporting.

pub fn try_timestamp(&self) -> Result<Timestamp, TypeError>

More efficient shortcut for .decode().as_timestamp() with error reporting.

pub fn try_bytes(&self) -> Result<Cow<'_, [u8]>, TypeError>

More efficient shortcut for .decode().to_bytes() with error reporting.

pub fn try_str(&self) -> Result<Cow<'_, str>, TypeError>

More efficient shortcut for .decode().to_str() with error reporting.

pub fn try_array(&self) -> Result<Vec<Cow<'_, Cbor>>, TypeError>

More efficient shortcut for .decode().to_array() with error reporting.

pub fn try_dict( &self ) -> Result<BTreeMap<Cow<'_, Cbor>, Cow<'_, Cbor>>, TypeError>

More efficient shortcut for .decode().to_dict() with error reporting.

pub fn index<'a, 'b>( &'a self, path: impl IntoIterator<Item = PathElement<'b>> ) -> Option<Cow<'a, Cbor>>

Extract a value by indexing into arrays and dicts, with path elements yielded by an iterator.

Returns None if an index doesn’t exist or the indexed object is neither an array nor a dict. When the object under consideration is an array, the next path element must represent an integer number.

Providing an empty iterator will yield the current Cbor item.

Returns a borrowed Cbor unless the traversal entered a TAG_CBOR_ITEM byte string with indefinite encoding (in which case the bytes need to be assembled into a Vec before continuing). This cannot happen if the item being indexed stems from CborOwned::canonical.

pub fn index_borrowed<'a, 'b>( &'a self, path: impl IntoIterator<Item = PathElement<'b>> ) -> Option<&'a Cbor>

Extract a value by indexing into arrays and dicts, with path elements yielded by an iterator.

Returns None if an index doesn’t exist or the indexed object is neither an array nor a dict. When the object under consideration is an array, the next path element must represent an integer number.

Providing an empty iterator will yield the current Cbor item.

Panics

Panics if this CBOR item contains a TAG_CBOR_ITEM byte string that has been index into by this path traversal. Use CborOwned::canonical to ensure that this cannot happen.

pub fn visit<'a, 'b, Err, V: Visitor<'a, Err> + 'b>( &'a self, visitor: &'b mut V ) -> Result<(), Err>

Visit the interesting parts of this CBOR item as guided by the given Visitor.

Returns false if the visit was not even begun due to invalid or non-canonical CBOR.

Trait Implementations

impl AsRef<[u8]> for Cbor

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Cbor> for CborOwned

fn as_ref(&self) -> &Cbor

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<Cbor> for CborOwned

fn borrow(&self) -> &Cbor

Immutably borrows from an owned value.

impl Debug for Cbor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Cbor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&Cbor> for SmallVec<[u8; 16]>

fn from(a: &Cbor) -> Self

Converts to this type from the input type.

impl Hash for Cbor

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

impl Ord for Cbor

fn cmp(&self, other: &Cbor) -> Ordering

This method returns an Ordering between self and other.

impl PartialEq for Cbor

fn eq(&self, other: &Cbor) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Cbor

fn partial_cmp(&self, other: &Cbor) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> ReadCborBorrowed<'a> for Cbor

fn read_cbor_borrowed(cbor: &'a Cbor) -> Result<Cow<'a, Self>>

impl ToOwned for Cbor

type Owned = CborOwned

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl<'a> TryFrom<&'a [u8]> for &'a Cbor

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(value: &'a [u8]) -> Result<Self, Self::Error>

Performs the conversion.

impl WriteCbor for Cbor

fn write_cbor<W: Writer>(&self, w: W) -> W::Output

impl Eq for Cbor

impl StructuralPartialEq for Cbor