futures_byteorder/
lib.rs

1//! A modern async byteorder library for the smol/futures-lite ecosystem.
2//!
3//! This crate provides utilities for reading and writing numbers in big-endian and
4//! little-endian byte order for async I/O streams. It's designed as a modern alternative
5//! to the `byteorder` crate, with first-class async support using `futures-lite`.
6//!
7//! # Features
8//!
9//! - Async-first API using `futures-lite`
10//! - Support for all integer types (`u8`-`u128`, `i8`-`i128`) and floats (`f32`, `f64`)
11//! - Big-endian, little-endian, and native-endian support
12//! - Zero-cost abstractions with const generics
13//! - No unsafe code
14//!
15//! # Examples
16//!
17//! ## Reading
18//!
19//! ```no_run
20//! use futures_byteorder::{AsyncReadBytes, BE};
21//! use futures_lite::io::Cursor;
22//!
23//! # async fn example() -> std::io::Result<()> {
24//! let data = vec![0x12, 0x34, 0x56, 0x78];
25//! let mut reader = Cursor::new(data);
26//! let mut reader = AsyncReadBytes::new(&mut reader);
27//!
28//! // Read a big-endian u16
29//! let value = reader.read_u16::<BE>().await?;
30//! assert_eq!(value, 0x1234);
31//!
32//! // Read using native endianness
33//! let value = reader.read_u16_ne().await?;
34//! # Ok(())
35//! # }
36//! ```
37//!
38//! ## Writing
39//!
40//! ```no_run
41//! use futures_byteorder::{AsyncWriteBytes, LE};
42//! use futures_lite::io::Cursor;
43//!
44//! # async fn example() -> std::io::Result<()> {
45//! let mut buffer = Vec::new();
46//! let mut writer = Cursor::new(&mut buffer);
47//! let mut writer = AsyncWriteBytes::new(&mut writer);
48//!
49//! // Write a little-endian u32
50//! writer.write_u32::<LE>(0x12345678).await?;
51//!
52//! // Write using native endianness
53//! writer.write_u16_ne(0xABCD).await?;
54//! # Ok(())
55//! # }
56//! ```
57//!
58//! # Endianness Types
59//!
60//! - [`BigEndian`] (alias [`BE`]) - Big-endian byte order
61//! - [`LittleEndian`] (alias [`LE`]) - Little-endian byte order
62//! - [`NativeEndian`] (alias [`NE`]) - Platform's native byte order
63//! - [`NetworkEndian`] - Network byte order (same as [`BE`])
64
65mod read;
66mod traits;
67mod write;
68
69#[cfg(test)]
70mod tests;
71
72pub use crate::read::*;
73pub use crate::traits::{Endianness, Representable};
74pub use crate::write::*;
75
76/// Defines big-endian serialization.
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
78pub struct BigEndian;
79
80/// Defines little-endian serialization.
81#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
82pub struct LittleEndian;
83
84/// Defines network byte order serialization. (type alias for [`BigEndian`])
85pub type NetworkEndian = BE;
86
87#[cfg(target_endian = "little")]
88/// Defines system native-endian serialization.
89/// On this platform, this is an alias for [`LittleEndian`].
90pub type NativeEndian = LE;
91
92#[cfg(target_endian = "big")]
93/// Defines system native-endian serialization.
94/// On this platform, this is an alias for [`BigEndian`].
95pub type NativeEndian = BE;
96
97/// Type alias for [`BigEndian`].
98pub type BE = BigEndian;
99
100/// Type alias for [`LittleEndian`].
101pub type LE = LittleEndian;
102
103/// Type alias for [`NativeEndian`].
104/// Note: Not to be confused with [`NetworkEndian`]!
105pub type NE = NativeEndian;
futures_byteorder/lib.rs

futures_byteorder/
lib.rs
