# cboritem
## cboritem: A serialized CBOR item
A [`CborItem<'a>`] is a newtype around `&'a u8` that upholds the invariant of containing a
single serialized CBOR item. A [`ThinCborItem<'a>`] is its start pointer; when accessing it,
users rely on that property to stop reading at the end of the item.
In a sense, the types are similar to [`&str`] and [`core::ffi::CStr`'], respectively, once the
latter follows the [plan] of eventually becoming a thin pointer.
### Library use
Their use is for efficiently storing pre-verified slices of CBOR items, eg. when implementing
[packed CBOR]. They can also serve as an interface point between CBOR libraries (easing error
handling because end-of-stream and bytes-after-the-data errors are panic-worthy invariants;
other parsing errors may still occur if there is any well-formed data the parser can not
process, or that violates basic validity requirements), and as a marker type by which CBOR
parsers can be instructed to process any item into a slice for later detailed inspection.
This crate is not a CBOR library, thus it contains no functions to safely create any of its
types (as that requires a CBOR parser). Instead, its intention is to be produced by CBOR
parsers after they have verified that the invariant upholds.
### Invariant definition
The invariant upheld in this crate's types is that their bytes are exactly one well-formed CBOR
item as defined in [RFC8949]; in particular, that means they contain at least one byte.
### Examples
```rust
use cboritem::{CborItem, ThinCborItem};
let onehundred = [0x24, 0x64];
assert_eq!(onehundred[0], 0x24);
let onehundred = unsafe { CborItem::new(&onehundred) };
let onehundred: ThinCborItem<'_> = onehundred.as_thin();
assert_eq!(core::mem::size_of_val(&onehundred), core::mem::size_of::<&u8>());
// One byte can always be read, so we don't need a CBOR parser to tell us it is safe
if onehundred.first() == 0x24 {
assert_eq!(unsafe { onehundred.offset(1).read() }, 100);
} else {
panic!("Unexpected type or integer size");
}
```
### Future development
Later versions may add types or variants of the current types (by means of associated types
with a default), eg. to descibe additional constraints such as
* Embedded strings are UTF-8
* No duplicate keys are present
* Adhers to the Common Deterministic Encoding
* Contains no indefinite-length items
* The CBOR item conforms to some particular CDDL structure
If any extensions are made that change CBOR's validity rules (eg. i=28 is defined for 128-bit
integer arguments), this crate would go through a major release to support them.
[plan]: https://internals.rust-lang.org/t/pre-rfc-make-cstr-a-thin-pointer/6258
[packed CBOR]: https://datatracker.ietf.org/doc/draft-ietf-cbor-packed/
[RFC8949]: https://datatracker.ietf.org/doc/html/rfc8949
License: MIT OR Apache-2.0