osal_rs_serde/
de.rs

1/***************************************************************************
2 *
3 * osal-rs-serde
4 * Copyright (C) 2026 Antonio Salsi <passy.linux@zresa.it>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library 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 GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <https://www.gnu.org/licenses/>.
18 *
19 ***************************************************************************/
20
21//! Deserialization traits and implementations.
22//!
23//! This module provides the core deserialization functionality for osal-rs-serde.
24//! It defines the [`Deserialize`] trait for types that can be deserialized and the
25//! [`Deserializer`] trait for implementing custom deserialization formats.
26//!
27//! # Overview
28//!
29//! - [`Deserialize`]: Trait implemented by types that can be deserialized
30//! - [`Deserializer`]: Trait for implementing custom deserialization formats  
31//! - [`ByteDeserializer`]: Concrete implementation that reads little-endian binary data
32//!
33//! # Usage with Derive Macro
34//!
35//! The easiest way to implement deserialization is using the derive macro:
36//!
37//! ```ignore
38//! use osal_rs_serde::Deserialize;
39//!
40//! #[derive(Deserialize)]
41//! struct SensorData {
42//!     temperature: i16,
43//!     humidity: u8,
44//!     pressure: u32,
45//! }
46//! ```
47//!
48//! # Manual Implementation
49//!
50//! For custom deserialization logic, implement the trait manually:
51//!
52//! ```ignore
53//! use osal_rs_serde::{Deserialize, Deserializer};
54//!
55//! struct Point {
56//!     x: i32,
57//!     y: i32,
58//! }
59//!
60//! impl Deserialize for Point {
61//!     fn deserialize<D: Deserializer>(deserializer: &mut D, _name: &str) -> Result<Self, D::Error> {
62//!         Ok(Point {
63//!             x: deserializer.deserialize_i32("x")?,
64//!             y: deserializer.deserialize_i32("y")?,
65//!         })
66//!     }
67//! }
68//! ```
69//!
70//! # Supported Types
71//!
72//! The deserialization framework supports:
73//! - All primitive types (bool, integers, floats)
74//! - Arrays `[T; N]` where T: Deserialize
75//! - Tuples (up to 3 elements)
76//! - `Option<T>` where T: Deserialize
77//! - `Vec<T>` where T: Deserialize (requires `alloc`)
78//! - `String` (requires `alloc`)
79//! - Custom types implementing `Deserialize`
80
81#[cfg(feature = "alloc")]
82use alloc::string::String;
83
84#[cfg(feature = "alloc")]
85use alloc::vec::Vec;
86
87use crate::error::{Error, Result};
88
89/// Trait for types that can be deserialized.
90///
91/// This trait should be implemented (or derived) for any type that needs to be deserialized.
92/// The implementation defines how the type should be read from a deserializer.
93///
94/// # Derive Macro
95///
96/// The easiest way to implement this trait is using the derive macro (requires `derive` feature):
97///
98/// ```ignore
99/// use osal_rs_serde::Deserialize;
100///
101/// #[derive(Deserialize)]
102/// struct Config {
103///     id: u32,
104///     enabled: bool,
105///     timeout: Option<u16>,
106/// }
107/// ```
108///
109/// # Manual Implementation
110///
111/// For custom deserialization logic or types not supported by the derive macro:
112///
113/// ```ignore
114/// use osal_rs_serde::{Deserialize, Deserializer};
115///
116/// struct Point {
117///     x: i32,
118///     y: i32,
119/// }
120///
121/// impl Deserialize for Point {
122///     fn deserialize<D: Deserializer>(deserializer: &mut D, _name: &str) -> core::result::Result<Self, D::Error> {
123///         Ok(Point {
124///             x: deserializer.deserialize_i32("x")?,
125///             y: deserializer.deserialize_i32("y")?,
126///         })
127///     }
128/// }
129/// ```
130///
131/// # Built-in Implementations
132///
133/// This trait is already implemented for:
134/// - All primitive types (bool, u8-u128, i8-i128, f32, f64)
135/// - Arrays `[T; N]` where T: Deserialize
136/// - Tuples (T1, T2) and (T1, T2, T3) where all T: Deserialize
137/// - `Option<T>` where T: Deserialize
138/// - `Vec<T>` where T: Deserialize (requires `alloc`)
139/// - `String` (requires `alloc`)
140pub trait Deserialize: Sized {
141    /// Deserialize this value using the given deserializer.
142    /// The `name` parameter contains the field name or struct name for context.
143    fn deserialize<D>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error>
144    where
145        D: Deserializer;
146}
147
148/// Trait that defines how to deserialize various types.
149///
150/// Implementations of this trait determine how to read data from a specific format.
151/// For example, `ByteDeserializer` reads data in little-endian binary format.
152pub trait Deserializer: Sized {
153    /// The error type that can be returned during deserialization.
154    type Error: From<Error>;
155
156    /// Deserialize a `bool` value.
157    fn deserialize_bool(&mut self, name: &str) -> core::result::Result<bool, Self::Error>;
158
159    /// Deserialize a `u8` value.
160    fn deserialize_u8(&mut self, name: &str) -> core::result::Result<u8, Self::Error>;
161
162    /// Deserialize an `i8` value.
163    fn deserialize_i8(&mut self, name: &str) -> core::result::Result<i8, Self::Error>;
164
165    /// Deserialize a `u16` value.
166    fn deserialize_u16(&mut self, name: &str) -> core::result::Result<u16, Self::Error>;
167
168    /// Deserialize an `i16` value.
169    fn deserialize_i16(&mut self, name: &str) -> core::result::Result<i16, Self::Error>;
170
171    /// Deserialize a `u32` value.
172    fn deserialize_u32(&mut self, name: &str) -> core::result::Result<u32, Self::Error>;
173
174    /// Deserialize an `i32` value.
175    fn deserialize_i32(&mut self, name: &str) -> core::result::Result<i32, Self::Error>;
176
177    /// Deserialize a `u64` value.
178    fn deserialize_u64(&mut self, name: &str) -> core::result::Result<u64, Self::Error>;
179
180    /// Deserialize an `i64` value.
181    fn deserialize_i64(&mut self, name: &str) -> core::result::Result<i64, Self::Error>;
182
183    /// Deserialize a `u128` value.
184    fn deserialize_u128(&mut self, name: &str) -> core::result::Result<u128, Self::Error>;
185
186    /// Deserialize an `i128` value.
187    fn deserialize_i128(&mut self, name: &str) -> core::result::Result<i128, Self::Error>;
188
189    /// Deserialize an `f32` value.
190    fn deserialize_f32(&mut self, name: &str) -> core::result::Result<f32, Self::Error>;
191
192    /// Deserialize an `f64` value.
193    fn deserialize_f64(&mut self, name: &str) -> core::result::Result<f64, Self::Error>;
194
195    /// Deserialize bytes into a buffer. Returns the number of bytes read.
196    fn deserialize_bytes(&mut self, name: &str, buffer: &mut [u8]) -> core::result::Result<usize, Self::Error>;
197
198    /// Deserialize a string.
199    #[cfg(feature = "alloc")]
200    fn deserialize_string(&mut self, name: &str) -> core::result::Result<String, Self::Error>;
201
202    /// Deserialize a vector of deserializable items.
203    #[cfg(feature = "alloc")]
204    fn deserialize_vec<T>(&mut self, name: &str) -> core::result::Result<Vec<T>, Self::Error>
205    where 
206        T: Deserialize;
207
208    /// Deserialize an array of deserializable items.
209    fn deserialize_array<T, const N: usize>(&mut self, name: &str) -> core::result::Result<[T; N], Self::Error>
210    where 
211        T: Deserialize;
212
213    /// Begin deserializing a struct with the given name.
214    fn deserialize_struct_start(&mut self, _name: &str) -> core::result::Result<(), Self::Error> {
215        Ok(())
216    }
217
218    /// Deserialize a struct field with name.
219    fn deserialize_field<T>(&mut self, name: &str) -> core::result::Result<T, Self::Error> 
220    where
221        T: Deserialize {
222        T::deserialize(self, name)
223    }
224
225    /// End deserializing a struct.
226    fn deserialize_struct_end(&mut self) -> core::result::Result<(), Self::Error> {
227        Ok(())
228    }
229}
230
231/// A deserializer that reads data from a byte buffer in little-endian format.
232///
233/// This is a concrete implementation of the `Deserializer` trait that reads
234/// binary data in a compact, little-endian format. This is the default deserializer
235/// used by the [`crate::from_bytes`] convenience function.
236///
237/// # Format
238///
239/// This deserializer expects data in the same format as [`crate::ser::ByteSerializer`]:
240/// - All integers in little-endian byte order
241/// - Floating-point numbers in IEEE 754 representation
242/// - `bool` as a single byte (0 or 1)
243/// - `Option<T>`: 1 byte tag (0=None, 1=Some) followed by T if Some
244/// - Arrays: Elements deserialized sequentially (no length prefix expected)
245/// - Tuples: Elements deserialized sequentially
246/// - Strings/Vec: u32 length prefix followed by data
247///
248/// # Examples
249///
250/// ## Basic Usage
251///
252/// ```ignore
253/// use osal_rs_serde::{ByteDeserializer, Deserializer};
254///
255/// let buffer = [42u8, 0, 0, 0, 1, 156, 255];
256/// let mut deserializer = ByteDeserializer::new(&buffer);
257///
258/// let value1 = deserializer.deserialize_u32("").unwrap();
259/// let value2 = deserializer.deserialize_bool("").unwrap();
260/// let value3 = deserializer.deserialize_i16("").unwrap();
261///
262/// assert_eq!(value1, 42);
263/// assert_eq!(value2, true);
264/// assert_eq!(value3, -100);
265/// ```
266///
267/// ## With Structs
268///
269/// ```ignore
270/// use osal_rs_serde::{ByteDeserializer, Deserialize, from_bytes};
271///
272/// #[derive(Deserialize)]
273/// struct Message {
274///     id: u32,
275///     value: i16,
276/// }
277///
278/// let buffer = [100, 0, 0, 0, 206, 255]; // id=100, value=-50 in little-endian
279/// let msg: Message = from_bytes(&buffer).unwrap();
280///
281/// assert_eq!(msg.id, 100);
282/// assert_eq!(msg.value, -50);
283/// ```
284///
285/// # Error Handling
286///
287/// Returns [`Error::UnexpectedEof`](crate::error::Error::UnexpectedEof) if the buffer
288/// doesn't contain enough data for the requested type.
289///
290/// # Memory Layout
291///
292/// The deserializer reads data sequentially without expecting padding or alignment:
293///
294/// ```text
295/// struct Data { a: u16, b: u32 }
296/// Memory: [a_lo, a_hi, b0, b1, b2, b3]
297/// ```
298pub struct ByteDeserializer<'a> {
299    buffer: &'a [u8],
300    position: usize,
301}
302
303impl<'a> ByteDeserializer<'a> {
304    /// Create a new ByteDeserializer with the given buffer.
305    pub fn new(buffer: &'a [u8]) -> Self {
306        Self {
307            buffer,
308            position: 0,
309        }
310    }
311
312    /// Get the current position in the buffer.
313    pub fn position(&self) -> usize {
314        self.position
315    }
316
317    /// Read bytes from the buffer.
318    fn read_bytes(&mut self, len: usize) -> Result<&[u8]> {
319        if self.position + len > self.buffer.len() {
320            return Err(Error::UnexpectedEof);
321        }
322        let bytes = &self.buffer[self.position..self.position + len];
323        self.position += len;
324        Ok(bytes)
325    }
326}
327
328impl<'a> Deserializer for ByteDeserializer<'a> {
329    type Error = Error;
330
331    fn deserialize_bool(&mut self, _name: &str) -> Result<bool> {
332        Ok(self.deserialize_u8("")? != 0)
333    }
334
335    fn deserialize_u8(&mut self, _name: &str) -> Result<u8> {
336        let bytes = self.read_bytes(1)?;
337        Ok(bytes[0])
338    }
339
340    fn deserialize_i8(&mut self, _name: &str) -> Result<i8> {
341        let bytes = self.read_bytes(1)?;
342        Ok(i8::from_le_bytes([bytes[0]]))
343    }
344
345    fn deserialize_u16(&mut self, _name: &str) -> Result<u16> {
346        let bytes = self.read_bytes(2)?;
347        let mut buf = [0u8; 2];
348        buf.copy_from_slice(bytes);
349        Ok(u16::from_le_bytes(buf))
350    }
351
352    fn deserialize_i16(&mut self, _name: &str) -> Result<i16> {
353        let bytes = self.read_bytes(2)?;
354        let mut buf = [0u8; 2];
355        buf.copy_from_slice(bytes);
356        Ok(i16::from_le_bytes(buf))
357    }
358
359    fn deserialize_u32(&mut self, _name: &str) -> Result<u32> {
360        let bytes = self.read_bytes(4)?;
361        let mut buf = [0u8; 4];
362        buf.copy_from_slice(bytes);
363        Ok(u32::from_le_bytes(buf))
364    }
365
366    fn deserialize_i32(&mut self, _name: &str) -> Result<i32> {
367        let bytes = self.read_bytes(4)?;
368        let mut buf = [0u8; 4];
369        buf.copy_from_slice(bytes);
370        Ok(i32::from_le_bytes(buf))
371    }
372
373    fn deserialize_u64(&mut self, _name: &str) -> Result<u64> {
374        let bytes = self.read_bytes(8)?;
375        let mut buf = [0u8; 8];
376        buf.copy_from_slice(bytes);
377        Ok(u64::from_le_bytes(buf))
378    }
379
380    fn deserialize_i64(&mut self, _name: &str) -> Result<i64> {
381        let bytes = self.read_bytes(8)?;
382        let mut buf = [0u8; 8];
383        buf.copy_from_slice(bytes);
384        Ok(i64::from_le_bytes(buf))
385    }
386
387    fn deserialize_u128(&mut self, _name: &str) -> Result<u128> {
388        let bytes = self.read_bytes(16)?;
389        let mut buf = [0u8; 16];
390        buf.copy_from_slice(bytes);
391        Ok(u128::from_le_bytes(buf))
392    }
393
394    fn deserialize_i128(&mut self, _name: &str) -> Result<i128> {
395        let bytes = self.read_bytes(16)?;
396        let mut buf = [0u8; 16];
397        buf.copy_from_slice(bytes);
398        Ok(i128::from_le_bytes(buf))
399    }
400
401    fn deserialize_f32(&mut self, _name: &str) -> Result<f32> {
402        let bytes = self.read_bytes(4)?;
403        let mut buf = [0u8; 4];
404        buf.copy_from_slice(bytes);
405        Ok(f32::from_le_bytes(buf))
406    }
407
408    fn deserialize_f64(&mut self, _name: &str) -> Result<f64> {
409        let bytes = self.read_bytes(8)?;
410        let mut buf = [0u8; 8];
411        buf.copy_from_slice(bytes);
412        Ok(f64::from_le_bytes(buf))
413    }
414
415    fn deserialize_bytes(&mut self, _name: &str, buffer: &mut [u8]) -> Result<usize> {
416        // First read the length
417        let len = self.deserialize_u32("")? as usize;
418        if len > buffer.len() {
419            return Err(Error::BufferTooSmall);
420        }
421        let bytes = self.read_bytes(len)?;
422        buffer[..len].copy_from_slice(bytes);
423        Ok(len)
424    }
425
426    #[cfg(feature = "alloc")]
427    fn deserialize_string(&mut self, _name: &str) -> Result<String> {
428        let len = self.deserialize_u32("")? as usize;
429        let bytes = self.read_bytes(len)?;
430        String::from_utf8(bytes.to_vec())
431            .map_err(|_| Error::InvalidData)
432    }
433
434    #[cfg(feature = "alloc")]
435    fn deserialize_vec<T>(&mut self, _name: &str) -> Result<Vec<T>> 
436    where 
437        T: Deserialize {
438        let len = self.deserialize_u32("")? as usize;
439        let mut vec = Vec::with_capacity(len);
440        for _ in 0..len {
441            vec.push(T::deserialize(self, "")?);
442        }
443        Ok(vec)
444    }
445
446    fn deserialize_array<T, const N: usize>(&mut self, _name: &str) -> Result<[T; N]> 
447    where
448        T: Deserialize {
449        let mut result = core::mem::MaybeUninit::<[T; N]>::uninit();
450        let result_ptr = result.as_mut_ptr() as *mut T;
451        
452        for i in 0..N {
453            unsafe {
454                result_ptr.add(i).write(T::deserialize(self, "")?);
455            }
456        }
457        
458        Ok(unsafe { result.assume_init() })
459    }
460}
461
462// Implementations for primitive types
463
464impl Deserialize for bool {
465    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
466        deserializer.deserialize_bool(name)
467    }
468}
469
470impl Deserialize for u8 {
471    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
472        deserializer.deserialize_u8(name)
473    }
474}
475
476impl Deserialize for i8 {
477    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
478        deserializer.deserialize_i8(name)
479    }
480}
481
482impl Deserialize for u16 {
483    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
484        deserializer.deserialize_u16(name)
485    }
486}
487
488impl Deserialize for i16 {
489    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
490        deserializer.deserialize_i16(name)
491    }
492}
493
494impl Deserialize for u32 {
495    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
496        deserializer.deserialize_u32(name)
497    }
498}
499
500impl Deserialize for i32 {
501    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
502        deserializer.deserialize_i32(name)
503    }
504}
505
506impl Deserialize for u64 {
507    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
508        deserializer.deserialize_u64(name)
509    }
510}
511
512impl Deserialize for i64 {
513    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
514        deserializer.deserialize_i64(name)
515    }
516}
517
518impl Deserialize for u128 {
519    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
520        deserializer.deserialize_u128(name)
521    }
522}
523
524impl Deserialize for i128 {
525    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
526        deserializer.deserialize_i128(name)
527    }
528}
529
530impl Deserialize for f32 {
531    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
532        deserializer.deserialize_f32(name)
533    }
534}
535
536impl Deserialize for f64 {
537    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
538        deserializer.deserialize_f64(name)
539    }
540}
541
542#[cfg(feature = "alloc")]
543impl Deserialize for String {
544    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
545        deserializer.deserialize_string(name)
546    }
547}
548
549// Array implementation
550impl<T, const N: usize> Deserialize for [T; N] 
551where 
552    T: Deserialize 
553{
554    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
555        deserializer.deserialize_array::<T, N>(name)
556    }
557}
558
559// Vec implementation
560#[cfg(feature = "alloc")]
561impl<T> Deserialize for Vec<T>
562where
563    T: Deserialize
564{
565    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
566        deserializer.deserialize_vec::<T>(name)
567    }
568}
569
570// Tuple implementations
571impl<T1: Deserialize, T2: Deserialize> Deserialize for (T1, T2) 
572where
573    T1: Deserialize,
574    T2: Deserialize
575{
576    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
577        Ok((
578            T1::deserialize(deserializer, name)?,
579            T2::deserialize(deserializer, name)?,
580        ))
581    }
582}
583
584impl<T1: Deserialize, T2: Deserialize, T3: Deserialize> Deserialize for (T1, T2, T3)
585where
586    T1: Deserialize,
587    T2: Deserialize,
588    T3: Deserialize,
589{
590    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
591        Ok((
592            T1::deserialize(deserializer, name)?,
593            T2::deserialize(deserializer, name)?,
594            T3::deserialize(deserializer, name)?,
595        ))
596    }
597}
598
599// Option implementation
600impl<T> Deserialize for Option<T> 
601where T: Deserialize
602{
603    fn deserialize<D: Deserializer>(deserializer: &mut D, name: &str) -> core::result::Result<Self, D::Error> {
604        let tag = deserializer.deserialize_u8(name)?;
605        match tag {
606            0 => Ok(None),
607            1 => Ok(Some(T::deserialize(deserializer, name)?)),
608            _ => Err(Error::InvalidData.into()),
609        }
610    }
611}
osal_rs_serde/de.rs

osal_rs_serde/
de.rs
