spectrusty_formats/
lib.rs

1/*
2    Copyright (C) 2020-2022  Rafal Michalski
3
4    This file is part of SPECTRUSTY, a Rust library for building emulators.
5
6    SPECTRUSTY is free software: you can redistribute it and/or modify it under
7    the terms of the GNU Lesser General Public License (LGPL) as published
8    by the Free Software Foundation, either version 3 of the License, or
9    (at your option) any later version.
10
11    SPECTRUSTY is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14    GNU Lesser General Public License for more details.
15
16    You should have received a copy of the GNU Lesser General Public License
17    along with this program.  If not, see <https://www.gnu.org/licenses/>.
18
19    Author contact information: see Cargo.toml file, section [package.authors].
20*/
21//! ZX Spectrum related file format utilities.
22use std::io::{self, Read, Write};
23
24pub mod ay;
25pub mod mdr;
26pub mod sna;
27pub mod tap;
28pub mod snapshot;
29pub mod scr;
30pub mod z80;
31// pub mod tzx;
32
33/// A trait that extends [Read] with methods that ease reading from chunked files.
34pub trait ReadExactEx: Read {
35    /// Reads all bytes to fill `buf` or until EOF. If successful, returns the total number of bytes read.
36    ///
37    /// This function behaves like [Read::read_to_end] but it reads data into the mutable slice
38    /// instead of into a Vec and stops reading when the whole `buf` has been filled.
39    fn read_exact_or_to_end(&mut self, mut buf: &mut[u8]) -> io::Result<usize> {
40        let orig_len = buf.len();
41        while !buf.is_empty() {
42            match self.read(buf) {
43                Ok(0) => break,
44                Ok(n) => buf = &mut buf[n..],
45                Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {}
46                Err(e) => return Err(e),
47            }
48        }
49        Ok(orig_len - buf.len())
50    }
51    /// Reads the exact number of bytes required to fill `buf` and returns `Ok(true)` or returns
52    /// `Ok(false)` if exactly zero bytes were read. In this instance, `buf` will be left unmodified.
53    ///
54    /// If at least one byte was read, this function behaves exactly like [Read::read_exact].
55    fn read_exact_or_none(&mut self, buf: &mut [u8]) -> io::Result<bool> {
56        let bytes_read = self.read_exact_or_to_end(buf)?;
57        if bytes_read == 0 {
58            Ok(false)
59        }
60        else if bytes_read == buf.len() {
61            Ok(true)
62        }
63        else {
64            Err(io::Error::new(io::ErrorKind::UnexpectedEof, "failed to fill whole buffer"))
65        }
66    }
67}
68
69impl<R: Read> ReadExactEx for R {}
70
71/// # Safety
72/// This trait can be implemented safely only with packed structs that solely consist of
73/// `u8` or array of `u8` primitives.
74pub(crate) unsafe trait StructRead: Copy {
75    fn read_new_struct<R: Read>(rd: R) -> io::Result<Self> where Self: Default {
76        let mut obj = Self::default();
77        obj.read_struct(rd)?;
78        Ok(obj)
79    }
80
81    fn read_struct<R: Read>(&mut self, mut rd: R) -> io::Result<()> {
82        rd.read_exact(unsafe { struct_slice_mut(self) })
83    }
84
85    fn read_struct_or_nothing<R: ReadExactEx>(&mut self, mut rd: R) -> io::Result<bool> {
86        rd.read_exact_or_none(unsafe { struct_slice_mut(self) })
87    }
88    /// Reads the struct only up to the given `limit` bytes.
89    ///
90    /// # Panics
91    /// Panics if `limit` is larger than the size of the struct.
92    fn read_struct_with_limit<R: Read>(&mut self, mut rd: R, limit: usize) -> io::Result<()> {
93        let slice = unsafe { struct_slice_mut(self) };
94        rd.read_exact(&mut slice[0..limit])
95    }
96}
97
98/// # Safety
99/// This trait can be implemented safely only with packed structs that solely consist of
100/// `u8` or array of `u8` primitives.
101pub(crate) unsafe trait StructWrite: Copy {
102    fn write_struct<W: Write>(&self, mut wr: W) -> io::Result<()> {
103        let slice = unsafe { struct_slice_ref(self) };
104        wr.write_all(slice)
105    }
106
107    fn write_struct_with_limit<W: Write>(&self, mut wr: W, limit: usize) -> io::Result<()> {
108        let slice = unsafe { struct_slice_ref(self) };
109        wr.write_all(&slice[0..limit])
110    }
111}
112
113/// # Safety
114/// This function can be used safely only with packed structs that solely consist of
115/// `u8` or array of `u8` primitives.
116unsafe fn struct_slice_mut<T: Copy>(obj: &mut T) -> &mut [u8] {
117    let len = core::mem::size_of::<T>() / core::mem::size_of::<u8>();
118    core::slice::from_raw_parts_mut(obj as *mut T as *mut u8, len)
119}
120
121/// # Safety
122/// This function can be used safely only with packed structs that solely consist of
123/// `u8` or array of `u8` primitives.
124unsafe fn struct_slice_ref<T: Copy>(obj: &T) -> &[u8] {
125    let len = core::mem::size_of::<T>() / core::mem::size_of::<u8>();
126    core::slice::from_raw_parts(obj as *const T as *const u8, len)
127}
spectrusty_formats/lib.rs

spectrusty_formats/
lib.rs
