Skip to main content

arrow_buffer/
native.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use crate::{IntervalDayTime, IntervalMonthDayNano, i256};
6use half::f16;
7
8mod private {
9    pub trait Sealed {}
10}
11
12// Required so that `[T]` satisfies the `Sealed` supertrait of `ToByteSlice`.
13impl<T: ArrowNativeType> private::Sealed for [T] {}
14
15/// Trait expressing a Rust type that has the same in-memory representation as
16/// Arrow.
17///
18/// This includes `i16`, `f32`, but excludes `bool` (which in arrow is
19/// represented in bits).
20///
21/// In little endian machines, types that implement [`ArrowNativeType`] can be
22/// memcopied to arrow buffers as is.
23///
24/// # Transmute Safety
25///
26/// A type T implementing this trait means that any arbitrary slice of bytes of length and
27/// alignment `size_of::<T>()` can be safely interpreted as a value of that type without
28/// being unsound, i.e. potentially resulting in undefined behaviour.
29///
30/// Note: in the case of floating point numbers this transmutation can result in a signalling
31/// NaN, which, whilst sound, can be unwieldy. In general, whilst it is perfectly sound to
32/// reinterpret bytes as different types using this trait, it is likely unwise. For more information
33/// see [f32::from_bits] and [f64::from_bits].
34///
35/// Note: `bool` is restricted to `0` or `1`, and so `bool: !ArrowNativeType`
36///
37/// # Sealed
38///
39/// Due to the above restrictions, this trait is sealed to prevent accidental misuse
40pub trait ArrowNativeType:
41    std::fmt::Debug + Send + Sync + Copy + PartialOrd + Default + private::Sealed + 'static
42{
43    /// Returns the byte width of this native type.
44    fn get_byte_width() -> usize {
45        std::mem::size_of::<Self>()
46    }
47
48    /// Convert native integer type from usize
49    ///
50    /// Returns `None` if [`Self`] is not an integer or conversion would result
51    /// in truncation/overflow
52    fn from_usize(_: usize) -> Option<Self>;
53
54    /// Convert to usize according to the [`as`] operator
55    ///
56    /// [`as`]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#numeric-cast
57    fn as_usize(self) -> usize;
58
59    /// Convert from usize according to the [`as`] operator
60    ///
61    /// [`as`]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#numeric-cast
62    fn usize_as(i: usize) -> Self;
63
64    /// Convert native type to usize.
65    ///
66    /// Returns `None` if [`Self`] is not an integer or conversion would result
67    /// in truncation/overflow
68    fn to_usize(self) -> Option<usize>;
69
70    /// Convert native type to isize.
71    ///
72    /// Returns `None` if [`Self`] is not an integer or conversion would result
73    /// in truncation/overflow
74    fn to_isize(self) -> Option<isize>;
75
76    /// Convert native type to i64.
77    ///
78    /// Returns `None` if [`Self`] is not an integer or conversion would result
79    /// in truncation/overflow
80    fn to_i64(self) -> Option<i64>;
81}
82
83macro_rules! native_integer {
84    ($t: ty $(, $from:ident)*) => {
85        impl private::Sealed for $t {}
86        impl ArrowNativeType for $t {
87            #[inline]
88            fn from_usize(v: usize) -> Option<Self> {
89                v.try_into().ok()
90            }
91
92            #[inline]
93            fn to_usize(self) -> Option<usize> {
94                self.try_into().ok()
95            }
96
97            #[inline]
98            fn to_isize(self) -> Option<isize> {
99                self.try_into().ok()
100            }
101
102            #[inline]
103            fn to_i64(self) -> Option<i64> {
104                self.try_into().ok()
105            }
106
107            #[inline]
108            fn as_usize(self) -> usize {
109                self as _
110            }
111
112            #[inline]
113            fn usize_as(i: usize) -> Self {
114                i as _
115            }
116        }
117    };
118}
119
120native_integer!(i8);
121native_integer!(i16);
122native_integer!(i32);
123native_integer!(i64);
124native_integer!(i128);
125native_integer!(u8);
126native_integer!(u16);
127native_integer!(u32);
128native_integer!(u64);
129native_integer!(u128);
130
131macro_rules! native_float {
132    ($t:ty, $s:ident, $as_usize: expr, $i:ident, $usize_as: expr) => {
133        impl private::Sealed for $t {}
134        impl ArrowNativeType for $t {
135            #[inline]
136            fn from_usize(_: usize) -> Option<Self> {
137                None
138            }
139
140            #[inline]
141            fn to_usize(self) -> Option<usize> {
142                None
143            }
144
145            #[inline]
146            fn to_isize(self) -> Option<isize> {
147                None
148            }
149
150            #[inline]
151            fn to_i64(self) -> Option<i64> {
152                None
153            }
154
155            #[inline]
156            fn as_usize($s) -> usize {
157                $as_usize
158            }
159
160            #[inline]
161            fn usize_as($i: usize) -> Self {
162                $usize_as
163            }
164        }
165    };
166}
167
168native_float!(f16, self, self.to_f32() as _, i, f16::from_f32(i as _));
169native_float!(f32, self, self as _, i, i as _);
170native_float!(f64, self, self as _, i, i as _);
171
172impl private::Sealed for i256 {}
173impl ArrowNativeType for i256 {
174    fn from_usize(u: usize) -> Option<Self> {
175        Some(Self::from_parts(u as u128, 0))
176    }
177
178    fn as_usize(self) -> usize {
179        self.to_parts().0 as usize
180    }
181
182    fn usize_as(i: usize) -> Self {
183        Self::from_parts(i as u128, 0)
184    }
185
186    fn to_usize(self) -> Option<usize> {
187        let (low, high) = self.to_parts();
188        if high != 0 {
189            return None;
190        }
191        low.try_into().ok()
192    }
193
194    fn to_isize(self) -> Option<isize> {
195        self.to_i128()?.try_into().ok()
196    }
197
198    fn to_i64(self) -> Option<i64> {
199        self.to_i128()?.try_into().ok()
200    }
201}
202
203impl private::Sealed for IntervalMonthDayNano {}
204impl ArrowNativeType for IntervalMonthDayNano {
205    fn from_usize(_: usize) -> Option<Self> {
206        None
207    }
208
209    fn as_usize(self) -> usize {
210        ((self.months as u64) | ((self.days as u64) << 32)) as usize
211    }
212
213    fn usize_as(i: usize) -> Self {
214        Self::new(i as _, ((i as u64) >> 32) as _, 0)
215    }
216
217    fn to_usize(self) -> Option<usize> {
218        None
219    }
220
221    fn to_isize(self) -> Option<isize> {
222        None
223    }
224
225    fn to_i64(self) -> Option<i64> {
226        None
227    }
228}
229
230impl private::Sealed for IntervalDayTime {}
231impl ArrowNativeType for IntervalDayTime {
232    fn from_usize(_: usize) -> Option<Self> {
233        None
234    }
235
236    fn as_usize(self) -> usize {
237        ((self.days as u64) | ((self.milliseconds as u64) << 32)) as usize
238    }
239
240    fn usize_as(i: usize) -> Self {
241        Self::new(i as _, ((i as u64) >> 32) as _)
242    }
243
244    fn to_usize(self) -> Option<usize> {
245        None
246    }
247
248    fn to_isize(self) -> Option<isize> {
249        None
250    }
251
252    fn to_i64(self) -> Option<i64> {
253        None
254    }
255}
256
257/// Allows conversion from supported Arrow types to a byte slice.
258pub trait ToByteSlice: private::Sealed {
259    /// Converts this instance into a byte slice
260    fn to_byte_slice(&self) -> &[u8];
261}
262
263impl<T: ArrowNativeType> ToByteSlice for [T] {
264    #[inline]
265    fn to_byte_slice(&self) -> &[u8] {
266        let raw_ptr = self.as_ptr().cast::<u8>();
267        unsafe { std::slice::from_raw_parts(raw_ptr, std::mem::size_of_val(self)) }
268    }
269}
270
271impl<T: ArrowNativeType> ToByteSlice for T {
272    #[inline]
273    fn to_byte_slice(&self) -> &[u8] {
274        let raw_ptr = std::ptr::from_ref::<T>(self).cast::<u8>();
275        unsafe { std::slice::from_raw_parts(raw_ptr, std::mem::size_of::<T>()) }
276    }
277}
278
279#[cfg(test)]
280mod tests {
281    use super::*;
282
283    #[test]
284    fn test_i256() {
285        let a = i256::from_parts(0, 0);
286        assert_eq!(a.as_usize(), 0);
287        assert_eq!(a.to_usize().unwrap(), 0);
288        assert_eq!(a.to_isize().unwrap(), 0);
289
290        let a = i256::from_parts(0, -1);
291        assert_eq!(a.as_usize(), 0);
292        assert!(a.to_usize().is_none());
293        assert!(a.to_usize().is_none());
294
295        let a = i256::from_parts(u128::MAX, -1);
296        assert_eq!(a.as_usize(), usize::MAX);
297        assert!(a.to_usize().is_none());
298        assert_eq!(a.to_isize().unwrap(), -1);
299    }
300
301    #[test]
302    fn test_interval_usize() {
303        assert_eq!(IntervalDayTime::new(1, 0).as_usize(), 1);
304        assert_eq!(IntervalMonthDayNano::new(1, 0, 0).as_usize(), 1);
305
306        let a = IntervalDayTime::new(23, 53);
307        let b = IntervalDayTime::usize_as(a.as_usize());
308        assert_eq!(a, b);
309
310        let a = IntervalMonthDayNano::new(23, 53, 0);
311        let b = IntervalMonthDayNano::usize_as(a.as_usize());
312        assert_eq!(a, b);
313    }
314}