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 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263
//! This crate provides an alternative API for reading and writing data in an //! endianness that might only be known at run-time. It encapsulates the //! existing capabilities of the [`byteorder`] crate with an interface that //! assumes an implicitly acknowledged byte order. //! //! The benefits of this API is two-fold. This crate supports use cases where //! the data's endianness is only known during program execution, which may //! happen in some formats and protocols. The same API can be used to reduce //! redundancy by indicating the intended byte order once for the entire //! routine, instead of once for each method call. //! //! The main contribution in this crate is the [`ByteOrdered`] wrapper type, //! which infuses byte order information to a data source or destination (it //! works for both readers and writers). Moreover, the [`Endian`] trait //! contains multiple primitive data reading and writing methods, and the //! [`Endianness`] type provides a basic enumerate for endianness information //! only known at run-time. //! //! # Examples //! //! Use one of [`ByteOrdered`]'s constructors to create a wrapper with byte //! order awareness. //! //! ```no_run //! use byteordered::{ByteOrdered, Endianness}; //! # use std::error::Error; //! # use std::io::Read; //! //! # fn get_data_source() -> Result<Box<Read>, Box<Error>> { //! # unimplemented!() //! # } //! # fn run() -> Result<(), Box<Error>> { //! let mut rd = ByteOrdered::le(get_data_source()?); // little endian //! // read a u16 //! let w = rd.read_u16()?; //! // choose to read the following data in Little Endian if it's //! // smaller than 256, otherwise read in Big Endian //! let mut rd = rd.into_endianness(Endianness::le_iff(w < 256)); //! let value: u32 = rd.read_u32()?; //! # Ok(()) //! # } //! # fn main() { //! # run().unwrap(); //! # } //! ``` //! //! Both `byteordered` and [`byteorder`] work well side by side. You can use //! [`byteorder`] in one part of //! the routine, and wrap the reader or writer when deemed useful. //! //! ``` //! # extern crate byteorder; //! # extern crate byteordered; //! use byteorder::ReadBytesExt; //! use byteordered::{ByteOrdered, Endianness}; //! # use std::error::Error; //! # use std::io::Read; //! //! # fn get_data_source() -> Result<Box<Read>, Box<Error>> { unimplemented!() } //! # fn run() -> Result<(), Box<Error>> { //! let b = 5; //! // choose to read the following data in Little Endian if it's 0, //! // otherwise read in Big Endian (what happens in this case) //! let mut wt = ByteOrdered::runtime( //! Vec::new(), //! if b == 0 { Endianness::Little } else { Endianness::Big } //! ); //! // write in this byte order //! wt.write_u16(0xC000)?; //! wt.write_u32(0)?; //! // then invert the byte order //! let mut wt = wt.into_opposite(); //! wt.write_u16(0xEEFF)?; //! assert_eq!(&*wt.into_inner(), &[0xC0, 0, 0, 0, 0, 0, 0xFF, 0xEE]); //! # Ok(()) //! # } //! # fn main() { //! # run().unwrap(); //! # } //! ``` //! //! As an additional construct, the [`with_order!`] macro is another API for //! reading and writing data, with the perk of providing explicit //! monomorphization with respect to the given endianness. //! //! ```no_run //! # #[macro_use] extern crate byteordered; //! # use byteordered::Endianness; //! # use std::error::Error; //! # use std::io::Read; //! # fn get_data_source() -> Result<Box<Read>, Box<Error>> { //! # unimplemented!() //! # } //! # fn run() -> Result<(), Box<Error>> { //! with_order!(get_data_source()?, Endianness::Little, |rd| { //! let value: u32 = rd.read_u32()?; //! println!("-> {}", value); //! }); //! # Ok(()) //! # } //! # fn main() { //! # run().unwrap(); //! # } //! ``` //! //! # Features //! //! `i128` enables reading and writing 128-bit integers, as in [`byteorder`]. //! This library requires the standard library (`no_std` is currently not //! supported). //! //! [`byteorder`]: https://docs.rs/byteorder //! [`Endian`]: trait.Endian.html //! [`Endianness`]: enum.Endianness.html //! [`ByteOrdered`]: struct.ByteOrdered.html //! [`with_order!`]: macro.with_order.html #![warn(missing_docs)] pub extern crate byteorder; mod base; mod wrap; pub use base::{Endian, Endianness, StaticEndianness}; pub use wrap::ByteOrdered; /// Creates a monomorphized scope for reading or writing with run-time byte /// order awareness. /// /// The condition of whether to read or write data in big endian or little /// endian is evaluated only once, at the beginning of the scope. The given /// expression `$e` is then monomorphized for both cases. /// /// The last argument is not a closure. It is only depicted as one to convey /// the familiar aspect of being provided a local variable. As such, the data /// source and other captured values are moved by default. /// /// # Examples /// /// Pass a [`ByteOrdered`] object, or a pair of data (source or destination) /// and endianness (typically [`Endianness`]). What follows is a pseudo-closure /// declaration exposing the same value with the expected byte order awareness. /// /// ``` /// # #[macro_use] extern crate byteordered; /// # use byteordered::Endianness; /// # fn get_endianness() -> Endianness { Endianness::Little } /// # fn run() -> Result<(), ::std::io::Error> { /// let e: Endianness = get_endianness(); /// let mut sink = Vec::new(); /// with_order!(&mut sink, e, |dest| { /// // dset is a `ByteOrdered<_, StaticEndianness<_>>` /// dest.write_u32(8)?; /// dest.write_u32(1024)?; /// dest.write_u32(0xF0FF_F0FF)?; /// }); /// assert_eq!(sink.len(), 12); /// # Ok(()) /// # } /// # fn main() { /// # run().unwrap(); /// # } /// ``` /// /// Moreover, you can pass multiple readers or writers to be augmented with /// the same implicit byte order. Note that the macro requires a literal tuple /// expression. /// /// ``` /// # #[macro_use] extern crate byteordered; /// # use byteordered::Endianness; /// # fn get_endianness() -> Endianness { Endianness::Little } /// # fn run() -> Result<(), ::std::io::Error> { /// let e: Endianness = get_endianness(); /// let (mut sink1, mut sink2) = (Vec::new(), Vec::new()); /// with_order!((&mut sink1, &mut sink2), e, |dest1, dest2| { /// dest1.write_u32(0x0000_EEFF)?; /// dest2.write_u32(0xFFEE_0000)?; /// }); /// assert_eq!(&sink1, &[0xFF, 0xEE, 0x00, 0x00]); /// assert_eq!(&sink2, &[0x00, 0x00, 0xEE, 0xFF]); /// # Ok(()) /// # } /// # fn main() { /// # run().unwrap(); /// # } /// ``` /// /// One might think that this always improves performance, since a /// runtime-bound `ByteOrdered` with a sequence of reads/writes would expand /// into one check for each method call: /// /// ```no_run /// # use byteordered::{ByteOrdered, Endianness}; /// # fn get_endianness() -> Endianness { Endianness::Little } /// # fn run() -> Result<(), ::std::io::Error> { /// let mut dst = ByteOrdered::runtime(Vec::new(), get_endianness()); /// // dynamic dispatch each time (or is it?) /// dst.write_u32(8)?; /// dst.write_u32(1024)?; /// dst.write_u32(0xF0FF_F0FF)?; /// # Ok(()) /// # } /// # run().unwrap(); /// ``` /// /// However, because the compiler is known to optimize these checks away in /// the same context, making a scope for that purpose is not always necessary. /// On the other hand, this will ensure that deeper function calls are /// monomorphized to a static endianness without making unnecessary run-time /// checks, specifically when function calls are not inlined. It can also be /// seen as yet another way to create and manage data sources/destinations with /// byte order awareness. /// /// [`ByteOrdered`]: struct.ByteOrdered.html /// [`Endianness`]: enum.Endianness.html #[macro_export] macro_rules! with_order { ($byteordered: expr, |$bo: ident| $e: expr) => { { let b = $byteordered; let e = b.endianness(); with_order!(b.into_inner(), e, |$bo| $e) } }; ( ($($src: expr ),*), $endianness: expr, |$($bo: ident ),*| $e: expr ) => { match $endianness { Endianness::Big => { $( let mut $bo = ::byteordered::ByteOrdered::new( $src, ::byteordered::StaticEndianness::<::byteordered::byteorder::BigEndian>::default()); )* $e } Endianness::Little => { $( let mut $bo = ::byteordered::ByteOrdered::new( $src, ::byteordered::StaticEndianness::<::byteordered::byteorder::LittleEndian>::default()); )* $e } } }; ($src: expr, $endianness: expr, |$bo: ident| $e: expr ) => { match $endianness { Endianness::Big => { let mut $bo = ::byteordered::ByteOrdered::new( $src, ::byteordered::StaticEndianness::<::byteordered::byteorder::BigEndian>::default()); $e } Endianness::Little => { let mut $bo = ::byteordered::ByteOrdered::new( $src, ::byteordered::StaticEndianness::<::byteordered::byteorder::LittleEndian>::default()); $e } } }; }