/Users/andrewlamb/Software/arrow-rs/arrow-buffer/src/native.rs

Source
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

use crate::{i256, IntervalDayTime, IntervalMonthDayNano};
use half::f16;

mod private {
    pub trait Sealed {}
}

/// Trait expressing a Rust type that has the same in-memory representation as
/// Arrow.
///
/// This includes `i16`, `f32`, but excludes `bool` (which in arrow is
/// represented in bits).
///
/// In little endian machines, types that implement [`ArrowNativeType`] can be
/// memcopied to arrow buffers as is.
///
/// # Transmute Safety
///
/// A type T implementing this trait means that any arbitrary slice of bytes of length and
/// alignment `size_of::<T>()` can be safely interpreted as a value of that type without
/// being unsound, i.e. potentially resulting in undefined behaviour.
///
/// Note: in the case of floating point numbers this transmutation can result in a signalling
/// NaN, which, whilst sound, can be unwieldy. In general, whilst it is perfectly sound to
/// reinterpret bytes as different types using this trait, it is likely unwise. For more information
/// see [f32::from_bits] and [f64::from_bits].
///
/// Note: `bool` is restricted to `0` or `1`, and so `bool: !ArrowNativeType`
///
/// # Sealed
///
/// Due to the above restrictions, this trait is sealed to prevent accidental misuse
pub trait ArrowNativeType:
    std::fmt::Debug + Send + Sync + Copy + PartialOrd + Default + private::Sealed + 'static
{
    /// Returns the byte width of this native type.
    fn get_byte_width() -> usize {
        std::mem::size_of::<Self>()
    }

    /// Convert native integer type from usize
    ///
    /// Returns `None` if [`Self`] is not an integer or conversion would result
    /// in truncation/overflow
    fn from_usize(_: usize) -> Option<Self>;

    /// Convert to usize according to the [`as`] operator
    ///
    /// [`as`]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#numeric-cast
    fn as_usize(self) -> usize;

    /// Convert from usize according to the [`as`] operator
    ///
    /// [`as`]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#numeric-cast
    fn usize_as(i: usize) -> Self;

    /// Convert native type to usize.
    ///
    /// Returns `None` if [`Self`] is not an integer or conversion would result
    /// in truncation/overflow
    fn to_usize(self) -> Option<usize>;

    /// Convert native type to isize.
    ///
    /// Returns `None` if [`Self`] is not an integer or conversion would result
    /// in truncation/overflow
    fn to_isize(self) -> Option<isize>;

    /// Convert native type to i64.
    ///
    /// Returns `None` if [`Self`] is not an integer or conversion would result
    /// in truncation/overflow
    fn to_i64(self) -> Option<i64>;
}

macro_rules! native_integer {
    ($t: ty $(, $from:ident)*) => {
        impl private::Sealed for $t {}
        impl ArrowNativeType for $t {
            #[inline]
            fn from_usize(v: usize) -> Option<Self> {
                v.try_into().ok()
            }

            #[inline]
            fn to_usize(self) -> Option<usize> {
                self.try_into().ok()
            }

            #[inline]
            fn to_isize(self) -> Option<isize> {
                self.try_into().ok()
            }

            #[inline]
            fn to_i64(self) -> Option<i64> {
                self.try_into().ok()
            }

            #[inline]
            fn as_usize(self) -> usize {
                self as _
            }

            #[inline]
            fn usize_as(i: usize) -> Self {
                i as _
            }
        }
    };
}

native_integer!(i8);
native_integer!(i16);
native_integer!(i32);
native_integer!(i64);
native_integer!(i128);
native_integer!(u8);
native_integer!(u16);
native_integer!(u32);
native_integer!(u64);
native_integer!(u128);

macro_rules! native_float {
    ($t:ty, $s:ident, $as_usize: expr, $i:ident, $usize_as: expr) => {
        impl private::Sealed for $t {}
        impl ArrowNativeType for $t {
            #[inline]
            fn from_usize(_: usize) -> Option<Self> {
                None
            }

            #[inline]
            fn to_usize(self) -> Option<usize> {
                None
            }

            #[inline]
            fn to_isize(self) -> Option<isize> {
                None
            }

            #[inline]
            fn to_i64(self) -> Option<i64> {
                None
            }

            #[inline]
            fn as_usize($s) -> usize {
                $as_usize
            }

            #[inline]
            fn usize_as($i: usize) -> Self {
                $usize_as
            }
        }
    };
}

native_float!(f16, self, self.to_f32() as _, i, f16::from_f32(i as _));
native_float!(f32, self, self as _, i, i as _);
native_float!(f64, self, self as _, i, i as _);

impl private::Sealed for i256 {}
impl ArrowNativeType for i256 {
    fn from_usize(u: usize) -> Option<Self> {
        Some(Self::from_parts(u as u128, 0))
    }

    fn as_usize(self) -> usize {
        self.to_parts().0 as usize
    }

    fn usize_as(i: usize) -> Self {
        Self::from_parts(i as u128, 0)
    }

    fn to_usize(self) -> Option<usize> {
        let (low, high) = self.to_parts();
        if high != 0 {
            return None;
        }
        low.try_into().ok()
    }

    fn to_isize(self) -> Option<isize> {
        self.to_i128()?.try_into().ok()
    }

    fn to_i64(self) -> Option<i64> {
        self.to_i128()?.try_into().ok()
    }
}

impl private::Sealed for IntervalMonthDayNano {}
impl ArrowNativeType for IntervalMonthDayNano {
    fn from_usize(_: usize) -> Option<Self> {
        None
    }

    fn as_usize(self) -> usize {
        ((self.months as u64) | ((self.days as u64) << 32)) as usize
    }

    fn usize_as(i: usize) -> Self {
        Self::new(i as _, ((i as u64) >> 32) as _, 0)
    }

    fn to_usize(self) -> Option<usize> {
        None
    }

    fn to_isize(self) -> Option<isize> {
        None
    }

    fn to_i64(self) -> Option<i64> {
        None
    }
}

impl private::Sealed for IntervalDayTime {}
impl ArrowNativeType for IntervalDayTime {
    fn from_usize(_: usize) -> Option<Self> {
        None
    }

    fn as_usize(self) -> usize {
        ((self.days as u64) | ((self.milliseconds as u64) << 32)) as usize
    }

    fn usize_as(i: usize) -> Self {
        Self::new(i as _, ((i as u64) >> 32) as _)
    }

    fn to_usize(self) -> Option<usize> {
        None
    }

    fn to_isize(self) -> Option<isize> {
        None
    }

    fn to_i64(self) -> Option<i64> {
        None
    }
}

/// Allows conversion from supported Arrow types to a byte slice.
pub trait ToByteSlice {
    /// Converts this instance into a byte slice
    fn to_byte_slice(&self) -> &[u8];
}

impl<T: ArrowNativeType> ToByteSlice for [T] {
    #[inline]
    fn to_byte_slice(&self) -> &[u8] {
        let raw_ptr = self.as_ptr() as *const u8;
        unsafe { std::slice::from_raw_parts(raw_ptr, std::mem::size_of_val(self)) }
    }
}

impl<T: ArrowNativeType> ToByteSlice for T {
    #[inline]
    fn to_byte_slice(&self) -> &[u8] {
        let raw_ptr = self as *const T as *const u8;
        unsafe { std::slice::from_raw_parts(raw_ptr, std::mem::size_of::<T>()) }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_i256() {
        let a = i256::from_parts(0, 0);
        assert_eq!(a.as_usize(), 0);
        assert_eq!(a.to_usize().unwrap(), 0);
        assert_eq!(a.to_isize().unwrap(), 0);

        let a = i256::from_parts(0, -1);
        assert_eq!(a.as_usize(), 0);
        assert!(a.to_usize().is_none());
        assert!(a.to_usize().is_none());

        let a = i256::from_parts(u128::MAX, -1);
        assert_eq!(a.as_usize(), usize::MAX);
        assert!(a.to_usize().is_none());
        assert_eq!(a.to_isize().unwrap(), -1);
    }

    #[test]
    fn test_interval_usize() {
        assert_eq!(IntervalDayTime::new(1, 0).as_usize(), 1);
        assert_eq!(IntervalMonthDayNano::new(1, 0, 0).as_usize(), 1);

        let a = IntervalDayTime::new(23, 53);
        let b = IntervalDayTime::usize_as(a.as_usize());
        assert_eq!(a, b);

        let a = IntervalMonthDayNano::new(23, 53, 0);
        let b = IntervalMonthDayNano::usize_as(a.as_usize());
        assert_eq!(a, b);
    }
}

Coverage Report

Created: 2025-08-26 07:03

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