Skip to content

Commit 75d4162

Browse files
committed
docs: document configurable sentinel, in-place decode, sentinel framing
Explain the 1.1.0 features with usage examples in the README.
1 parent d555943 commit 75d4162

1 file changed

Lines changed: 53 additions & 0 deletions

File tree

README.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,59 @@ let n = cobs::encode(&src, &mut buf);
6969
assert_eq!(&buf[..n], &[0x02, 0x11, 0x02, 0x22]);
7070
```
7171

72+
With a custom sentinel byte, so a non-`0x00` byte delimits frames (both `cobs`
73+
and `cobsr`, slice and `*_to_vec` variants):
74+
75+
```rust
76+
use cobs_codec_rs::cobs;
77+
78+
// 0xAA delimits frames instead of 0x00; the encoded output never contains it.
79+
// (`sentinel == 0` is identical to the plain codec.)
80+
let encoded = cobs::encode_to_vec_with_sentinel(&[0x11, 0xAA, 0x22], 0xAA);
81+
assert_eq!(encoded, [0xAE, 0xBB, 0x00, 0x88]); // no 0xAA byte
82+
assert_eq!(
83+
cobs::decode_to_vec_with_sentinel(&encoded, 0xAA).unwrap(),
84+
[0x11, 0xAA, 0x22],
85+
);
86+
```
87+
88+
Decoding in place, without a second buffer (basic COBS only):
89+
90+
```rust
91+
use cobs_codec_rs::cobs;
92+
93+
// COBS never expands on decode, so it can decode within the input buffer; the
94+
// decoded bytes end up in `buf[..len]`.
95+
let mut buf = [0x03, 0x11, 0x22, 0x02, 0x33];
96+
let len = cobs::decode_in_place(&mut buf).unwrap();
97+
assert_eq!(&buf[..len], &[0x11, 0x22, 0x00, 0x33]);
98+
```
99+
100+
Reassembling a sentinel-delimited stream with no allocator, into a fixed buffer:
101+
102+
```rust
103+
use cobs_codec_rs::cobs;
104+
use cobs_codec_rs::framing::StreamDecoder;
105+
106+
// Encode a packet with sentinel 0xAA, then delimit it with an 0xAA byte.
107+
let mut wire = [0u8; 16];
108+
let n = cobs::encode_with_sentinel(&[0x11, 0x00, 0x22], &mut wire, 0xAA);
109+
wire[n] = 0xAA;
110+
111+
// Reassemble it into a fixed scratch buffer — no allocation anywhere.
112+
let mut scratch = [0u8; 8];
113+
let mut decoder = StreamDecoder::new(&mut scratch).sentinel(0xAA); // .reduced(true) for COBS/R
114+
115+
let mut out = [0u8; 8];
116+
let mut out_len = 0;
117+
decoder.push(&wire[..n + 1], |frame| {
118+
let frame = frame.unwrap();
119+
out[..frame.len()].copy_from_slice(frame);
120+
out_len = frame.len();
121+
});
122+
assert_eq!(&out[..out_len], &[0x11, 0x00, 0x22]);
123+
```
124+
72125
Reading a delimited serial stream (needs `alloc`):
73126

74127
```rust

0 commit comments

Comments
 (0)