futures-byteorder 1.0.1

A modern async byteorder library for the smol/futures-lite ecosystem
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! A modern async byteorder library for the smol/futures-lite ecosystem.
//!
//! This crate provides utilities for reading and writing numbers in big-endian and
//! little-endian byte order for async I/O streams. It's designed as a modern alternative
//! to the `byteorder` crate, with first-class async support using `futures-lite`.
//!
//! # Features
//!
//! - Async-first API using `futures-lite`
//! - Support for all integer types (`u8`-`u128`, `i8`-`i128`) and floats (`f32`, `f64`)
//! - Big-endian, little-endian, and native-endian support
//! - Zero-cost abstractions with const generics
//! - No unsafe code
//!
//! # Examples
//!
//! ## Reading
//!
//! ```no_run
//! use futures_byteorder::{AsyncReadBytes, BE};
//! use futures_lite::io::Cursor;
//!
//! # async fn example() -> std::io::Result<()> {
//! let data = vec![0x12, 0x34, 0x56, 0x78];
//! let mut reader = Cursor::new(data);
//! let mut reader = AsyncReadBytes::new(&mut reader);
//!
//! // Read a big-endian u16
//! let value = reader.read_u16::<BE>().await?;
//! assert_eq!(value, 0x1234);
//!
//! // Read using native endianness
//! let value = reader.read_u16_ne().await?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Writing
//!
//! ```no_run
//! use futures_byteorder::{AsyncWriteBytes, LE};
//! use futures_lite::io::Cursor;
//!
//! # async fn example() -> std::io::Result<()> {
//! let mut buffer = Vec::new();
//! let mut writer = Cursor::new(&mut buffer);
//! let mut writer = AsyncWriteBytes::new(&mut writer);
//!
//! // Write a little-endian u32
//! writer.write_u32::<LE>(0x12345678).await?;
//!
//! // Write using native endianness
//! writer.write_u16_ne(0xABCD).await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Endianness Types
//!
//! - [`BigEndian`] (alias [`BE`]) - Big-endian byte order
//! - [`LittleEndian`] (alias [`LE`]) - Little-endian byte order
//! - [`NativeEndian`] (alias [`NE`]) - Platform's native byte order
//! - [`NetworkEndian`] - Network byte order (same as [`BE`])

mod read;
mod traits;
mod write;

#[cfg(test)]
mod tests;

pub use crate::read::*;
pub use crate::traits::{Endianness, Representable};
pub use crate::write::*;

/// Defines big-endian serialization.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct BigEndian;

/// Defines little-endian serialization.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct LittleEndian;

/// Defines network byte order serialization. (type alias for [`BigEndian`])
pub type NetworkEndian = BE;

#[cfg(target_endian = "little")]
/// Defines system native-endian serialization.
/// On this platform, this is an alias for [`LittleEndian`].
pub type NativeEndian = LE;

#[cfg(target_endian = "big")]
/// Defines system native-endian serialization.
/// On this platform, this is an alias for [`BigEndian`].
pub type NativeEndian = BE;

/// Type alias for [`BigEndian`].
pub type BE = BigEndian;

/// Type alias for [`LittleEndian`].
pub type LE = LittleEndian;

/// Type alias for [`NativeEndian`].
/// Note: Not to be confused with [`NetworkEndian`]!
pub type NE = NativeEndian;