codeq/
lib.rs

1//! A fully customized encode/decode library.
2//!
3//! **Differences from serde**: This crate focuses on a single, application defined binary format,
4//! built-in checksum support, simple encoding/decoding without intermediate formats,
5//! and application defined compatibility.
6//!
7//! Choose **this crate** when you need customized and simple binary serialization with checksums,
8//! or when data format evolves over time.
9//! Use **serde** when you need: multiple format support (JSON, YAML, etc.),
10//! or derive macros for automatic implementation.
11//!
12//! # Core Traits
13//!
14//! - [`Codec`], [`Encode`], [`Decode`]: Main trait for types that can be encoded/decoded
15//! - [`FixedSize`]: For types with known encoded size
16//! - [`Span`]: For types representing a region in a file/buffer
17//!
18//! # Utilities
19//!
20//! - [`ChecksumReader`]/[`ChecksumWriter`]: I/O wrappers that calculate checksums
21//! - [`WithChecksum<T>`]: Wraps data with checksum for integrity
22//! - [`Offset`]: Type-safe byte position in a file/buffer
23//! - [`Size`]: Type-safe byte length
24//! - [`OffsetReader`]/[`OffsetWriter`]: I/O wrappers that track current position
25//! - [`Segment<T>`]: Represents a typed region with offset and size
26//!
27//! # Examples
28//!
29//! Basic encoding and decoding:
30#![cfg_attr(not(feature = "crc32fast"), doc = "```ignore")]
31#![cfg_attr(feature = "crc32fast", doc = "```rust")]
32//! use codeq::{Codec, Decode, Encode, WithChecksum};
33//! # use std::io;
34//!
35//! use codeq::config::Crc32fast;
36//!
37//! #[derive(Debug, Clone, PartialEq)]
38//! struct Record {
39//!     id: u32,
40//!     data: Vec<u8>,
41//! }
42//!
43//! impl Encode for Record {
44//!     fn encode<W: io::Write>(&self, mut writer: W) -> io::Result<usize> {
45//!         let mut n = 0;
46//!         n += self.id.encode(&mut writer)?;
47//!         n += self.data.encode(&mut writer)?;
48//!         Ok(n)
49//!     }
50//! }
51//! impl Decode for Record {
52//!     fn decode<R: io::Read>(mut reader: R) -> io::Result<Self> {
53//!         Ok(Self {
54//!             id: u32::decode(&mut reader)?,
55//!             data: Vec::decode(&mut reader)?,
56//!         })
57//!     }
58//! }
59//!
60//! // Add checksum protection
61//! let record = Record { id: 1, data: vec![1, 2, 3] };
62//! let protected = WithChecksum::<Crc32fast,_>::new(&record);
63//!
64//! let mut buf = Vec::new();
65//! protected.encode(&mut buf).unwrap();
66//! assert_eq!(buf, vec![ //
67//!     0, 0, 0, 1, // id
68//!     0, 0, 0, 3, 1, 2, 3, // data
69//!     0, 0, 0, 0, 31, 101, 71, 147 // checksum
70//! ]);
71//!
72//! let decoded = Record::decode(&mut buf.as_slice()).unwrap();
73//! assert_eq!(record, decoded);
74//! ```
75//! 
76//! [`Codec`]: crate::Codec
77//! [`Encode`]: crate::Encode
78//! [`Decode`]: crate::Decode
79//! [`FixedSize`]: crate::FixedSize
80//! [`Span`]: crate::Span
81//! [`Offset`]: crate::Offset
82//! [`Size`]: crate::Size
83//! [`Segment<T>`]: crate::Segment
84//! [`WithChecksum<T>`]: crate::WithChecksum
85//! [`ChecksumReader`]: crate::ChecksumReader
86//! [`ChecksumWriter`]: crate::ChecksumWriter
87//! [`OffsetReader`]: crate::OffsetReader
88//! [`OffsetWriter`]: crate::OffsetWriter
89
90extern crate core;
91
92mod checksum_reader;
93mod checksum_writer;
94mod codec;
95mod fixed_size;
96mod offset_reader;
97mod offset_writer;
98mod segment;
99mod span;
100mod with_checksum;
101
102pub mod config;
103pub mod error_context_ext;
104pub(crate) mod sealed;
105pub mod testing;
106
107pub use checksum_reader::ChecksumReader;
108pub use checksum_writer::ChecksumWriter;
109pub use codec::Codec;
110pub use codec::Decode;
111pub use codec::Encode;
112pub use fixed_size::FixedSize;
113pub use offset_reader::OffsetReader;
114pub use offset_writer::OffsetWriter;
115pub use segment::Segment;
116pub use span::Offset;
117pub use span::Size;
118pub use span::Span;
119// Backward compatibility
120pub use span::Span as OffsetSize;
121pub use with_checksum::WithChecksum;
codeq/lib.rs

codeq/
lib.rs
