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
69pub use crate::read::*;
70pub use crate::traits::{Endianness, Representable};
71pub use crate::write::*;
72
73/// Defines big-endian serialization.
74#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
75pub struct BigEndian;
76
77/// Defines little-endian serialization.
78#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
79pub struct LittleEndian;
80
81/// Defines network byte order serialization. (type alias for [`BigEndian`])
82pub type NetworkEndian = BE;
83
84#[cfg(target_endian = "little")]
85/// Defines system native-endian serialization.
86/// On this platform, this is an alias for [`LittleEndian`].
87pub type NativeEndian = LE;
88
89#[cfg(target_endian = "big")]
90/// Defines system native-endian serialization.
91/// On this platform, this is an alias for [`BigEndian`].
92pub type NativeEndian = BE;
93
94/// Type alias for [`BigEndian`].
95pub type BE = BigEndian;
96
97/// Type alias for [`LittleEndian`].
98pub type LE = LittleEndian;
99
100/// Type alias for [`NativeEndian`].
101/// Note: Not to be confused with [`NetworkEndian`]!
102pub type NE = NativeEndian;
futures_byteorder/lib.rs

futures_byteorder/
lib.rs
