# cboritem  [](https://crates.io/crates/cboritem) [](https://docs.rs/cboritem) [](https://codeberg.org/chrysn/cboritem)
## cboritem: A serialized CBOR item
A [`CborItem<'a>`][__link0] is a newtype around [`&'a [u8]`][__link1] that upholds the invariant of
containing a single serialized CBOR item. A [`ThinCborItem<'a>`][__link2] 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`][__link3] and [`CStr`][__link4], respectively,
once the latter follows the [plan][__link5] 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][__link6]. 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][__link7]; in particular, that means they contain at least one byte.
The invariants in this crates are **soundness invariants**: Receivers of a CBOR item may not
just panic when they find invalid CBOR, but they may invoke undefined behavior (eg. by calling
[`unreachable_unchecked`][__link8]. Consequently, creating a CBOR
item requires use of the `unsafe` keyword, with the invariants being checked by the parser that
creates the item.
This is a necessary consequence of providing thin pointers: The invariants are relied on by
users who read through a raw pointer, which on inaccurate data would result in reads beyond the
original allocated object, which is undefined behavior.
### 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.
[__cargo_doc2readme_dependencies_info]: ggGkYW0BYXSEG_W_Gn_kaocAGwCcVPfenh7eGy6gYLEwyIe4G6-xw_FwcbpjYXKEG6Yy1ucqB8HyG7_7-eLiRsMRGz59Evt0Ie9DG-bow14s3BPmYWSBgmhjYm9yaXRlbWUwLjEuMw
[__link0]: https://docs.rs/cboritem/0.1.3/cboritem/struct.CborItem.html
[__link1]: https://doc.rust-lang.org/stable/std/primitive.u8.html
[__link2]: https://docs.rs/cboritem/0.1.3/cboritem/struct.ThinCborItem.html
[__link3]: https://doc.rust-lang.org/stable/std/primitive.str.html
[__link4]: https://doc.rust-lang.org/stable/core/?search=ffi::CStr
[__link5]: https://internals.rust-lang.org/t/pre-rfc-make-cstr-a-thin-pointer/6258
[__link6]: https://datatracker.ietf.org/doc/draft-ietf-cbor-packed/
[__link7]: https://datatracker.ietf.org/doc/html/rfc8949
[__link8]: https://doc.rust-lang.org/stable/core/?search=hint::unreachable_unchecked