Skip to main content

arrow_array/array/
primitive_array.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::array::print_long_array;
6use crate::builder::{BooleanBufferBuilder, PrimitiveBuilder};
7use crate::iterator::PrimitiveIter;
8use crate::temporal_conversions::{
9    as_datetime, as_datetime_with_data_type, as_datetime_with_timezone,
10    as_datetime_with_timezone_and_data_type, as_duration, as_time, as_time_with_data_type,
11};
12use crate::timezone::Tz;
13use crate::trusted_len::trusted_len_unzip;
14use crate::types::*;
15use crate::{Array, ArrayAccessor, ArrayRef, Scalar};
16use arrow_buffer::{ArrowNativeType, Buffer, NullBuffer, NullBufferBuilder, ScalarBuffer, i256};
17use arrow_data::bit_iterator::try_for_each_valid_idx;
18use arrow_data::{ArrayData, ArrayDataBuilder};
19use arrow_schema::{ArrowError, DataType};
20use chrono::{DateTime, Duration, NaiveDate, NaiveDateTime, NaiveTime};
21use half::f16;
22use std::any::Any;
23use std::sync::Arc;
24
25/// A [`PrimitiveArray`] of `i8`
26///
27/// # Examples
28///
29/// Construction
30///
31/// ```
32/// # use arrow_array::Int8Array;
33/// // Create from Vec<Option<i8>>
34/// let arr = Int8Array::from(vec![Some(1), None, Some(2)]);
35/// // Create from Vec<i8>
36/// let arr = Int8Array::from(vec![1, 2, 3]);
37/// // Create iter/collect
38/// let arr: Int8Array = std::iter::repeat(42).take(10).collect();
39/// ```
40///
41/// See [`PrimitiveArray`] for more information and examples
42pub type Int8Array = PrimitiveArray<Int8Type>;
43
44/// A [`PrimitiveArray`] of `i16`
45///
46/// # Examples
47///
48/// Construction
49///
50/// ```
51/// # use arrow_array::Int16Array;
52/// // Create from Vec<Option<i16>>
53/// let arr = Int16Array::from(vec![Some(1), None, Some(2)]);
54/// // Create from Vec<i16>
55/// let arr = Int16Array::from(vec![1, 2, 3]);
56/// // Create iter/collect
57/// let arr: Int16Array = std::iter::repeat(42).take(10).collect();
58/// ```
59///
60/// See [`PrimitiveArray`] for more information and examples
61pub type Int16Array = PrimitiveArray<Int16Type>;
62
63/// A [`PrimitiveArray`] of `i32`
64///
65/// # Examples
66///
67/// Construction
68///
69/// ```
70/// # use arrow_array::Int32Array;
71/// // Create from Vec<Option<i32>>
72/// let arr = Int32Array::from(vec![Some(1), None, Some(2)]);
73/// // Create from Vec<i32>
74/// let arr = Int32Array::from(vec![1, 2, 3]);
75/// // Create iter/collect
76/// let arr: Int32Array = std::iter::repeat(42).take(10).collect();
77/// ```
78///
79/// See [`PrimitiveArray`] for more information and examples
80pub type Int32Array = PrimitiveArray<Int32Type>;
81
82/// A [`PrimitiveArray`] of `i64`
83///
84/// # Examples
85///
86/// Construction
87///
88/// ```
89/// # use arrow_array::Int64Array;
90/// // Create from Vec<Option<i64>>
91/// let arr = Int64Array::from(vec![Some(1), None, Some(2)]);
92/// // Create from Vec<i64>
93/// let arr = Int64Array::from(vec![1, 2, 3]);
94/// // Create iter/collect
95/// let arr: Int64Array = std::iter::repeat(42).take(10).collect();
96/// ```
97///
98/// See [`PrimitiveArray`] for more information and examples
99pub type Int64Array = PrimitiveArray<Int64Type>;
100
101/// A [`PrimitiveArray`] of `u8`
102///
103/// # Examples
104///
105/// Construction
106///
107/// ```
108/// # use arrow_array::UInt8Array;
109/// // Create from Vec<Option<u8>>
110/// let arr = UInt8Array::from(vec![Some(1), None, Some(2)]);
111/// // Create from Vec<u8>
112/// let arr = UInt8Array::from(vec![1, 2, 3]);
113/// // Create iter/collect
114/// let arr: UInt8Array = std::iter::repeat(42).take(10).collect();
115/// ```
116///
117/// See [`PrimitiveArray`] for more information and examples
118pub type UInt8Array = PrimitiveArray<UInt8Type>;
119
120/// A [`PrimitiveArray`] of `u16`
121///
122/// # Examples
123///
124/// Construction
125///
126/// ```
127/// # use arrow_array::UInt16Array;
128/// // Create from Vec<Option<u16>>
129/// let arr = UInt16Array::from(vec![Some(1), None, Some(2)]);
130/// // Create from Vec<u16>
131/// let arr = UInt16Array::from(vec![1, 2, 3]);
132/// // Create iter/collect
133/// let arr: UInt16Array = std::iter::repeat(42).take(10).collect();
134/// ```
135///
136/// See [`PrimitiveArray`] for more information and examples
137pub type UInt16Array = PrimitiveArray<UInt16Type>;
138
139/// A [`PrimitiveArray`] of `u32`
140///
141/// # Examples
142///
143/// Construction
144///
145/// ```
146/// # use arrow_array::UInt32Array;
147/// // Create from Vec<Option<u32>>
148/// let arr = UInt32Array::from(vec![Some(1), None, Some(2)]);
149/// // Create from Vec<u32>
150/// let arr = UInt32Array::from(vec![1, 2, 3]);
151/// // Create iter/collect
152/// let arr: UInt32Array = std::iter::repeat(42).take(10).collect();
153/// ```
154///
155/// See [`PrimitiveArray`] for more information and examples
156pub type UInt32Array = PrimitiveArray<UInt32Type>;
157
158/// A [`PrimitiveArray`] of `u64`
159///
160/// # Examples
161///
162/// Construction
163///
164/// ```
165/// # use arrow_array::UInt64Array;
166/// // Create from Vec<Option<u64>>
167/// let arr = UInt64Array::from(vec![Some(1), None, Some(2)]);
168/// // Create from Vec<u64>
169/// let arr = UInt64Array::from(vec![1, 2, 3]);
170/// // Create iter/collect
171/// let arr: UInt64Array = std::iter::repeat(42).take(10).collect();
172/// ```
173///
174/// See [`PrimitiveArray`] for more information and examples
175pub type UInt64Array = PrimitiveArray<UInt64Type>;
176
177/// A [`PrimitiveArray`] of `f16`
178///
179/// # Examples
180///
181/// Construction
182///
183/// ```
184/// # use arrow_array::Float16Array;
185/// use half::f16;
186/// // Create from Vec<Option<f16>>
187/// let arr = Float16Array::from(vec![Some(f16::from_f64(1.0)), Some(f16::from_f64(2.0))]);
188/// // Create from Vec<i8>
189/// let arr = Float16Array::from(vec![f16::from_f64(1.0), f16::from_f64(2.0), f16::from_f64(3.0)]);
190/// // Create iter/collect
191/// let arr: Float16Array = std::iter::repeat(f16::from_f64(1.0)).take(10).collect();
192/// ```
193///
194/// # Example: Using `collect`
195/// ```
196/// # use arrow_array::Float16Array;
197/// use half::f16;
198/// let arr : Float16Array = [Some(f16::from_f64(1.0)), Some(f16::from_f64(2.0))].into_iter().collect();
199/// ```
200///
201/// See [`PrimitiveArray`] for more information and examples
202pub type Float16Array = PrimitiveArray<Float16Type>;
203
204/// A [`PrimitiveArray`] of `f32`
205///
206/// # Examples
207///
208/// Construction
209///
210/// ```
211/// # use arrow_array::Float32Array;
212/// // Create from Vec<Option<f32>>
213/// let arr = Float32Array::from(vec![Some(1.0), None, Some(2.0)]);
214/// // Create from Vec<f32>
215/// let arr = Float32Array::from(vec![1.0, 2.0, 3.0]);
216/// // Create iter/collect
217/// let arr: Float32Array = std::iter::repeat(42.0).take(10).collect();
218/// ```
219///
220/// See [`PrimitiveArray`] for more information and examples
221pub type Float32Array = PrimitiveArray<Float32Type>;
222
223/// A [`PrimitiveArray`] of `f64`
224///
225/// # Examples
226///
227/// Construction
228///
229/// ```
230/// # use arrow_array::Float64Array;
231/// // Create from Vec<Option<f32>>
232/// let arr = Float64Array::from(vec![Some(1.0), None, Some(2.0)]);
233/// // Create from Vec<f32>
234/// let arr = Float64Array::from(vec![1.0, 2.0, 3.0]);
235/// // Create iter/collect
236/// let arr: Float64Array = std::iter::repeat(42.0).take(10).collect();
237/// ```
238///
239/// See [`PrimitiveArray`] for more information and examples
240pub type Float64Array = PrimitiveArray<Float64Type>;
241
242/// A [`PrimitiveArray`] of seconds since UNIX epoch stored as `i64`
243///
244/// This type is similar to the [`chrono::DateTime`] type and can hold
245/// values such as `1970-05-09 14:25:11 +01:00`
246///
247/// See also [`Timestamp`](arrow_schema::DataType::Timestamp).
248///
249/// # Example: UTC timestamps post epoch
250/// ```
251/// # use arrow_array::TimestampSecondArray;
252/// use arrow_array::timezone::Tz;
253/// // Corresponds to single element array with entry 1970-05-09T14:25:11+0:00
254/// let arr = TimestampSecondArray::from(vec![11111111]);
255/// // OR
256/// let arr = TimestampSecondArray::from(vec![Some(11111111)]);
257/// let utc_tz: Tz = "+00:00".parse().unwrap();
258///
259/// assert_eq!(arr.value_as_datetime_with_tz(0, utc_tz).map(|v| v.to_string()).unwrap(), "1970-05-09 14:25:11 +00:00")
260/// ```
261///
262/// # Example: UTC timestamps pre epoch
263/// ```
264/// # use arrow_array::TimestampSecondArray;
265/// use arrow_array::timezone::Tz;
266/// // Corresponds to single element array with entry 1969-08-25T09:34:49+0:00
267/// let arr = TimestampSecondArray::from(vec![-11111111]);
268/// // OR
269/// let arr = TimestampSecondArray::from(vec![Some(-11111111)]);
270/// let utc_tz: Tz = "+00:00".parse().unwrap();
271///
272/// assert_eq!(arr.value_as_datetime_with_tz(0, utc_tz).map(|v| v.to_string()).unwrap(), "1969-08-25 09:34:49 +00:00")
273/// ```
274///
275/// # Example: With timezone specified
276/// ```
277/// # use arrow_array::TimestampSecondArray;
278/// use arrow_array::timezone::Tz;
279/// // Corresponds to single element array with entry 1970-05-10T00:25:11+10:00
280/// let arr = TimestampSecondArray::from(vec![11111111]).with_timezone("+10:00".to_string());
281/// // OR
282/// let arr = TimestampSecondArray::from(vec![Some(11111111)]).with_timezone("+10:00".to_string());
283/// let sydney_tz: Tz = "+10:00".parse().unwrap();
284///
285/// assert_eq!(arr.value_as_datetime_with_tz(0, sydney_tz).map(|v| v.to_string()).unwrap(), "1970-05-10 00:25:11 +10:00")
286/// ```
287///
288/// See [`PrimitiveArray`] for more information and examples
289pub type TimestampSecondArray = PrimitiveArray<TimestampSecondType>;
290
291/// A [`PrimitiveArray`] of milliseconds since UNIX epoch stored as `i64`
292///
293/// See examples for [`TimestampSecondArray`]
294pub type TimestampMillisecondArray = PrimitiveArray<TimestampMillisecondType>;
295
296/// A [`PrimitiveArray`] of microseconds since UNIX epoch stored as `i64`
297///
298/// See examples for [`TimestampSecondArray`]
299pub type TimestampMicrosecondArray = PrimitiveArray<TimestampMicrosecondType>;
300
301/// A [`PrimitiveArray`] of nanoseconds since UNIX epoch stored as `i64`
302///
303/// See examples for [`TimestampSecondArray`]
304pub type TimestampNanosecondArray = PrimitiveArray<TimestampNanosecondType>;
305
306/// A [`PrimitiveArray`] of days since UNIX epoch stored as `i32`
307///
308/// This type is similar to the [`chrono::NaiveDate`] type and can hold
309/// values such as `2018-11-13`
310pub type Date32Array = PrimitiveArray<Date32Type>;
311
312/// A [`PrimitiveArray`] of milliseconds since UNIX epoch stored as `i64`
313///
314/// This type is similar to the [`chrono::NaiveDate`] type and can hold
315/// values such as `2018-11-13`
316pub type Date64Array = PrimitiveArray<Date64Type>;
317
318/// A [`PrimitiveArray`] of seconds since midnight stored as `i32`
319///
320/// This type is similar to the [`chrono::NaiveTime`] type and can
321/// hold values such as `00:02:00`
322pub type Time32SecondArray = PrimitiveArray<Time32SecondType>;
323
324/// A [`PrimitiveArray`] of milliseconds since midnight stored as `i32`
325///
326/// This type is similar to the [`chrono::NaiveTime`] type and can
327/// hold values such as `00:02:00.123`
328pub type Time32MillisecondArray = PrimitiveArray<Time32MillisecondType>;
329
330/// A [`PrimitiveArray`] of microseconds since midnight stored as `i64`
331///
332/// This type is similar to the [`chrono::NaiveTime`] type and can
333/// hold values such as `00:02:00.123456`
334pub type Time64MicrosecondArray = PrimitiveArray<Time64MicrosecondType>;
335
336/// A [`PrimitiveArray`] of nanoseconds since midnight stored as `i64`
337///
338/// This type is similar to the [`chrono::NaiveTime`] type and can
339/// hold values such as `00:02:00.123456789`
340pub type Time64NanosecondArray = PrimitiveArray<Time64NanosecondType>;
341
342/// A [`PrimitiveArray`] of “calendar” intervals in whole months
343///
344/// See [`IntervalYearMonthType`] for details on representation and caveats.
345///
346/// # Example
347/// ```
348/// # use arrow_array::IntervalYearMonthArray;
349/// let array = IntervalYearMonthArray::from(vec![
350///   2,  // 2 months
351///   25, // 2 years and 1 month
352///   -1  // -1 months
353/// ]);
354/// ```
355pub type IntervalYearMonthArray = PrimitiveArray<IntervalYearMonthType>;
356
357/// A [`PrimitiveArray`] of “calendar” intervals in days and milliseconds
358///
359/// See [`IntervalDayTime`] for details on representation and caveats.
360///
361/// # Example
362/// ```
363/// # use arrow_array::IntervalDayTimeArray;
364/// use arrow_array::types::IntervalDayTime;
365/// let array = IntervalDayTimeArray::from(vec![
366///   IntervalDayTime::new(1, 1000),                 // 1 day, 1000 milliseconds
367///   IntervalDayTime::new(33, 0),                  // 33 days, 0 milliseconds
368///   IntervalDayTime::new(0, 12 * 60 * 60 * 1000), // 0 days, 12 hours
369/// ]);
370/// ```
371pub type IntervalDayTimeArray = PrimitiveArray<IntervalDayTimeType>;
372
373/// A [`PrimitiveArray`] of “calendar” intervals in  months, days, and nanoseconds.
374///
375/// See [`IntervalMonthDayNano`] for details on representation and caveats.
376///
377/// # Example
378/// ```
379/// # use arrow_array::IntervalMonthDayNanoArray;
380/// use arrow_array::types::IntervalMonthDayNano;
381/// let array = IntervalMonthDayNanoArray::from(vec![
382///   IntervalMonthDayNano::new(1, 2, 1000),             // 1 month, 2 days, 1 nanosecond
383///   IntervalMonthDayNano::new(12, 1, 0),               // 12 months, 1 days, 0 nanoseconds
384///   IntervalMonthDayNano::new(0, 0, 12 * 1000 * 1000), // 0 days, 12 milliseconds
385/// ]);
386/// ```
387pub type IntervalMonthDayNanoArray = PrimitiveArray<IntervalMonthDayNanoType>;
388
389/// A [`PrimitiveArray`] of elapsed durations in seconds
390pub type DurationSecondArray = PrimitiveArray<DurationSecondType>;
391
392/// A [`PrimitiveArray`] of elapsed durations in milliseconds
393pub type DurationMillisecondArray = PrimitiveArray<DurationMillisecondType>;
394
395/// A [`PrimitiveArray`] of elapsed durations in microseconds
396pub type DurationMicrosecondArray = PrimitiveArray<DurationMicrosecondType>;
397
398/// A [`PrimitiveArray`] of elapsed durations in nanoseconds
399pub type DurationNanosecondArray = PrimitiveArray<DurationNanosecondType>;
400
401/// A [`PrimitiveArray`] of 32-bit fixed point decimals
402///
403/// # Examples
404///
405/// Construction
406///
407/// ```
408/// # use arrow_array::Decimal32Array;
409/// // Create from Vec<Option<i32>>
410/// let arr = Decimal32Array::from(vec![Some(1), None, Some(2)]);
411/// // Create from Vec<i32>
412/// let arr = Decimal32Array::from(vec![1, 2, 3]);
413/// // Create iter/collect
414/// let arr: Decimal32Array = std::iter::repeat(42).take(10).collect();
415/// ```
416///
417/// See [`PrimitiveArray`] for more information and examples
418pub type Decimal32Array = PrimitiveArray<Decimal32Type>;
419
420/// A [`PrimitiveArray`] of 64-bit fixed point decimals
421///
422/// # Examples
423///
424/// Construction
425///
426/// ```
427/// # use arrow_array::Decimal64Array;
428/// // Create from Vec<Option<i64>>
429/// let arr = Decimal64Array::from(vec![Some(1), None, Some(2)]);
430/// // Create from Vec<i64>
431/// let arr = Decimal64Array::from(vec![1, 2, 3]);
432/// // Create iter/collect
433/// let arr: Decimal64Array = std::iter::repeat(42).take(10).collect();
434/// ```
435///
436/// See [`PrimitiveArray`] for more information and examples
437pub type Decimal64Array = PrimitiveArray<Decimal64Type>;
438
439/// A [`PrimitiveArray`] of 128-bit fixed point decimals
440///
441/// # Examples
442///
443/// Construction
444///
445/// ```
446/// # use arrow_array::Decimal128Array;
447/// // Create from Vec<Option<i128>>
448/// let arr = Decimal128Array::from(vec![Some(1), None, Some(2)]);
449/// // Create from Vec<i128>
450/// let arr = Decimal128Array::from(vec![1, 2, 3]);
451/// // Create iter/collect
452/// let arr: Decimal128Array = std::iter::repeat(42).take(10).collect();
453/// ```
454///
455/// See [`PrimitiveArray`] for more information and examples
456pub type Decimal128Array = PrimitiveArray<Decimal128Type>;
457
458/// A [`PrimitiveArray`] of 256-bit fixed point decimals
459///
460/// # Examples
461///
462/// Construction
463///
464/// ```
465/// # use arrow_array::Decimal256Array;
466/// use arrow_buffer::i256;
467/// // Create from Vec<Option<i256>>
468/// let arr = Decimal256Array::from(vec![Some(i256::from(1)), None, Some(i256::from(2))]);
469/// // Create from Vec<i256>
470/// let arr = Decimal256Array::from(vec![i256::from(1), i256::from(2), i256::from(3)]);
471/// // Create iter/collect
472/// let arr: Decimal256Array = std::iter::repeat(i256::from(42)).take(10).collect();
473/// ```
474///
475/// See [`PrimitiveArray`] for more information and examples
476pub type Decimal256Array = PrimitiveArray<Decimal256Type>;
477
478pub use crate::types::ArrowPrimitiveType;
479
480/// An array of primitive values, of type [`ArrowPrimitiveType`]
481///
482/// # Example: From a Vec
483///
484/// *Note*: Converting a `Vec` to a `PrimitiveArray` does not copy the data.
485/// The new `PrimitiveArray` uses the same underlying allocation from the `Vec`.
486///
487/// ```
488/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
489/// let arr: PrimitiveArray<Int32Type> = vec![1, 2, 3, 4].into();
490/// assert_eq!(4, arr.len());
491/// assert_eq!(0, arr.null_count());
492/// assert_eq!(arr.values(), &[1, 2, 3, 4])
493/// ```
494///
495/// # Example: To a `Vec<T>`
496///
497/// *Note*: In some cases, converting `PrimitiveArray` to a `Vec` is zero-copy
498/// and does not copy the data (see [`Buffer::into_vec`] for conditions). In
499/// such cases, the `Vec` will use the same underlying memory allocation from
500/// the `PrimitiveArray`.
501///
502/// The Rust compiler generates highly optimized code for operations on
503/// Vec, so using a Vec can often be faster than using a PrimitiveArray directly.
504///
505/// ```
506/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
507/// let arr = PrimitiveArray::<Int32Type>::from(vec![1, 2, 3, 4]);
508/// let starting_ptr = arr.values().as_ptr();
509/// // split into its parts
510/// let (datatype, buffer, nulls) = arr.into_parts();
511/// // Convert the buffer to a Vec<i32> (zero copy)
512/// // (note this requires that there are no other references)
513/// let mut vec: Vec<i32> = buffer.into();
514/// vec[2] = 300;
515/// // put the parts back together
516/// let arr = PrimitiveArray::<Int32Type>::try_new(vec.into(), nulls).unwrap();
517/// assert_eq!(arr.values(), &[1, 2, 300, 4]);
518/// // The same allocation was used
519/// assert_eq!(starting_ptr, arr.values().as_ptr());
520/// ```
521///
522/// # Example: From an optional Vec
523///
524/// ```
525/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
526/// let arr: PrimitiveArray<Int32Type> = vec![Some(1), None, Some(3), None].into();
527/// assert_eq!(4, arr.len());
528/// assert_eq!(2, arr.null_count());
529/// // Note: values for null indexes are arbitrary
530/// assert_eq!(arr.values(), &[1, 0, 3, 0])
531/// ```
532///
533/// # Example: From an iterator of values
534///
535/// ```
536/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
537/// let arr: PrimitiveArray<Int32Type> = (0..10).map(|x| x + 1).collect();
538/// assert_eq!(10, arr.len());
539/// assert_eq!(0, arr.null_count());
540/// for i in 0..10i32 {
541///     assert_eq!(i + 1, arr.value(i as usize));
542/// }
543/// ```
544///
545/// # Example: From an iterator of option
546///
547/// ```
548/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
549/// let arr: PrimitiveArray<Int32Type> = (0..10).map(|x| (x % 2 == 0).then_some(x)).collect();
550/// assert_eq!(10, arr.len());
551/// assert_eq!(5, arr.null_count());
552/// // Note: values for null indexes are arbitrary
553/// assert_eq!(arr.values(), &[0, 0, 2, 0, 4, 0, 6, 0, 8, 0])
554/// ```
555///
556/// # Example: Using Builder
557///
558/// ```
559/// # use arrow_array::Array;
560/// # use arrow_array::builder::PrimitiveBuilder;
561/// # use arrow_array::types::Int32Type;
562/// let mut builder = PrimitiveBuilder::<Int32Type>::new();
563/// builder.append_value(1);
564/// builder.append_null();
565/// builder.append_value(2);
566/// let array = builder.finish();
567/// // Note: values for null indexes are arbitrary
568/// assert_eq!(array.values(), &[1, 0, 2]);
569/// assert!(array.is_null(1));
570/// ```
571///
572/// # Performance: Choosing Between `from` and [`PrimitiveBuilder`]
573///
574/// Rust's `Vec` is highly optimized, and Arrow's conversion from `Vec` to
575/// `PrimitiveArray` is zero-copy. Prefer [`PrimitiveArray::from`] or
576/// [`PrimitiveArray::new`] whenever values are already in a `Vec` or can be collected
577/// into one. [`PrimitiveBuilder`] is backed by a `Vec` and a `NullBufferBuilder`
578/// internally, so it offers no performance advantage. Use it when the array may
579/// contain nulls whose positions aren't known upfront, since it keeps values and the
580/// null bitmask in sync automatically.
581///
582/// # Example: Get a `PrimitiveArray` from an [`ArrayRef`]
583/// ```
584/// # use std::sync::Arc;
585/// # use arrow_array::{Array, cast::AsArray, ArrayRef, Float32Array, PrimitiveArray};
586/// # use arrow_array::types::{Float32Type};
587/// # use arrow_schema::DataType;
588/// # let array: ArrayRef =  Arc::new(Float32Array::from(vec![1.2, 2.3]));
589/// // will panic if the array is not a Float32Array
590/// assert_eq!(&DataType::Float32, array.data_type());
591/// let f32_array: Float32Array  = array.as_primitive().clone();
592/// assert_eq!(f32_array, Float32Array::from(vec![1.2, 2.3]));
593/// ```
594pub struct PrimitiveArray<T: ArrowPrimitiveType> {
595    data_type: DataType,
596    /// Values data
597    values: ScalarBuffer<T::Native>,
598    nulls: Option<NullBuffer>,
599}
600
601impl<T: ArrowPrimitiveType> Clone for PrimitiveArray<T> {
602    fn clone(&self) -> Self {
603        Self {
604            data_type: self.data_type.clone(),
605            values: self.values.clone(),
606            nulls: self.nulls.clone(),
607        }
608    }
609}
610
611impl<T: ArrowPrimitiveType> PrimitiveArray<T> {
612    /// Create a new [`PrimitiveArray`] from the provided values and nulls
613    ///
614    /// # Panics
615    ///
616    /// Panics if [`Self::try_new`] returns an error
617    ///
618    /// # Example
619    ///
620    /// Creating a [`PrimitiveArray`] directly from a [`ScalarBuffer`] and [`NullBuffer`] using
621    /// this constructor is the most performant approach, avoiding any additional allocations
622    ///
623    /// ```
624    /// # use arrow_array::Int32Array;
625    /// # use arrow_array::types::Int32Type;
626    /// # use arrow_buffer::NullBuffer;
627    /// // [1, 2, 3, 4]
628    /// let array = Int32Array::new(vec![1, 2, 3, 4].into(), None);
629    /// // [1, null, 3, 4]
630    /// let nulls = NullBuffer::from(vec![true, false, true, true]);
631    /// let array = Int32Array::new(vec![1, 2, 3, 4].into(), Some(nulls));
632    /// ```
633    pub fn new(values: ScalarBuffer<T::Native>, nulls: Option<NullBuffer>) -> Self {
634        Self::try_new(values, nulls).unwrap()
635    }
636
637    /// Create a new [`PrimitiveArray`] from the provided values and nulls without validation.
638    ///
639    /// # Safety
640    /// - `values.len() == nulls.len()` if `nulls` is `Some`
641    pub unsafe fn new_unchecked(
642        values: ScalarBuffer<T::Native>,
643        nulls: Option<NullBuffer>,
644    ) -> Self {
645        if cfg!(feature = "force_validate") {
646            return Self::new(values, nulls);
647        }
648        Self {
649            data_type: T::DATA_TYPE,
650            values,
651            nulls,
652        }
653    }
654
655    /// Create a new [`PrimitiveArray`] of the given length where all values are null
656    pub fn new_null(length: usize) -> Self {
657        Self {
658            data_type: T::DATA_TYPE,
659            values: vec![T::Native::usize_as(0); length].into(),
660            nulls: Some(NullBuffer::new_null(length)),
661        }
662    }
663
664    /// Create a new [`PrimitiveArray`] from the provided values and nulls
665    ///
666    /// # Errors
667    ///
668    /// Errors if:
669    /// - `values.len() != nulls.len()`
670    pub fn try_new(
671        values: ScalarBuffer<T::Native>,
672        nulls: Option<NullBuffer>,
673    ) -> Result<Self, ArrowError> {
674        if let Some(n) = nulls.as_ref()
675            && n.len() != values.len()
676        {
677            return Err(ArrowError::InvalidArgumentError(format!(
678                "Incorrect length of null buffer for PrimitiveArray, expected {} got {}",
679                values.len(),
680                n.len(),
681            )));
682        }
683
684        Ok(Self {
685            data_type: T::DATA_TYPE,
686            values,
687            nulls,
688        })
689    }
690
691    /// Create a new [`Scalar`] from `value`
692    pub fn new_scalar(value: T::Native) -> Scalar<Self> {
693        Scalar::new(Self {
694            data_type: T::DATA_TYPE,
695            values: vec![value].into(),
696            nulls: None,
697        })
698    }
699
700    /// Deconstruct this array into its constituent parts
701    pub fn into_parts(self) -> (DataType, ScalarBuffer<T::Native>, Option<NullBuffer>) {
702        (self.data_type, self.values, self.nulls)
703    }
704
705    /// Overrides the [`DataType`] of this [`PrimitiveArray`]
706    ///
707    /// Prefer using [`Self::with_timezone`] or [`Self::with_precision_and_scale`] where
708    /// the primitive type is suitably constrained, as these cannot panic
709    ///
710    /// # Panics
711    ///
712    /// Panics if ![Self::is_compatible]
713    pub fn with_data_type(self, data_type: DataType) -> Self {
714        Self::assert_compatible(&data_type);
715        Self { data_type, ..self }
716    }
717
718    /// Asserts that `data_type` is compatible with `Self`
719    fn assert_compatible(data_type: &DataType) {
720        assert!(
721            Self::is_compatible(data_type),
722            "PrimitiveArray expected data type {} got {}",
723            T::DATA_TYPE,
724            data_type
725        );
726    }
727
728    /// Returns the length of this array.
729    #[inline]
730    pub fn len(&self) -> usize {
731        self.values.len()
732    }
733
734    /// Returns whether this array is empty.
735    pub fn is_empty(&self) -> bool {
736        self.values.is_empty()
737    }
738
739    /// Returns the values of this array
740    #[inline]
741    pub fn values(&self) -> &ScalarBuffer<T::Native> {
742        &self.values
743    }
744
745    /// Returns a new primitive array builder
746    pub fn builder(capacity: usize) -> PrimitiveBuilder<T> {
747        PrimitiveBuilder::<T>::with_capacity(capacity)
748    }
749
750    /// Returns if this [`PrimitiveArray`] is compatible with the provided [`DataType`]
751    ///
752    /// This is equivalent to `data_type == T::DATA_TYPE`, however ignores timestamp
753    /// timezones and decimal precision and scale
754    pub fn is_compatible(data_type: &DataType) -> bool {
755        match T::DATA_TYPE {
756            DataType::Timestamp(t1, _) => {
757                matches!(data_type, DataType::Timestamp(t2, _) if &t1 == t2)
758            }
759            DataType::Decimal32(_, _) => matches!(data_type, DataType::Decimal32(_, _)),
760            DataType::Decimal64(_, _) => matches!(data_type, DataType::Decimal64(_, _)),
761            DataType::Decimal128(_, _) => matches!(data_type, DataType::Decimal128(_, _)),
762            DataType::Decimal256(_, _) => matches!(data_type, DataType::Decimal256(_, _)),
763            _ => T::DATA_TYPE.eq(data_type),
764        }
765    }
766
767    /// Returns the primitive value at index `i`.
768    ///
769    /// Note: This method does not check for nulls and the value is arbitrary
770    /// if [`is_null`](Self::is_null) returns true for the index.
771    ///
772    /// # Safety
773    ///
774    /// caller must ensure that the passed in offset is less than the array len()
775    #[inline]
776    pub unsafe fn value_unchecked(&self, i: usize) -> T::Native {
777        unsafe { *self.values.get_unchecked(i) }
778    }
779
780    /// Returns the primitive value at index `i`.
781    ///
782    /// Note: This method does not check for nulls and the value is arbitrary
783    /// if [`is_null`](Self::is_null) returns true for the index.
784    ///
785    /// # Panics
786    /// Panics if index `i` is out of bounds
787    #[inline]
788    pub fn value(&self, i: usize) -> T::Native {
789        assert!(
790            i < self.len(),
791            "Trying to access an element at index {} from a PrimitiveArray of length {}",
792            i,
793            self.len()
794        );
795        unsafe { self.value_unchecked(i) }
796    }
797
798    /// Creates a PrimitiveArray based on an iterator of values without nulls
799    pub fn from_iter_values<I: IntoIterator<Item = T::Native>>(iter: I) -> Self {
800        let val_buf: Buffer = iter.into_iter().collect();
801        let len = val_buf.len() / std::mem::size_of::<T::Native>();
802        Self {
803            data_type: T::DATA_TYPE,
804            values: ScalarBuffer::new(val_buf, 0, len),
805            nulls: None,
806        }
807    }
808
809    /// Creates a PrimitiveArray based on an iterator of values with provided nulls
810    pub fn from_iter_values_with_nulls<I: IntoIterator<Item = T::Native>>(
811        iter: I,
812        nulls: Option<NullBuffer>,
813    ) -> Self {
814        let val_buf: Buffer = iter.into_iter().collect();
815        let len = val_buf.len() / std::mem::size_of::<T::Native>();
816        Self {
817            data_type: T::DATA_TYPE,
818            values: ScalarBuffer::new(val_buf, 0, len),
819            nulls,
820        }
821    }
822
823    /// Creates a PrimitiveArray based on a constant value with `count` elements
824    pub fn from_value(value: T::Native, count: usize) -> Self {
825        let val_buf: Vec<_> = vec![value; count];
826        Self::new(val_buf.into(), None)
827    }
828
829    /// Returns an iterator that returns the values of `array.value(i)` for an iterator with each element `i`
830    pub fn take_iter<'a>(
831        &'a self,
832        indexes: impl Iterator<Item = Option<usize>> + 'a,
833    ) -> impl Iterator<Item = Option<T::Native>> + 'a {
834        indexes.map(|opt_index| opt_index.map(|index| self.value(index)))
835    }
836
837    /// Returns an iterator that returns the values of `array.value(i)` for an iterator with each element `i`
838    /// # Safety
839    ///
840    /// caller must ensure that the offsets in the iterator are less than the array len()
841    pub unsafe fn take_iter_unchecked<'a>(
842        &'a self,
843        indexes: impl Iterator<Item = Option<usize>> + 'a,
844    ) -> impl Iterator<Item = Option<T::Native>> + 'a {
845        indexes.map(|opt_index| opt_index.map(|index| unsafe { self.value_unchecked(index) }))
846    }
847
848    /// Returns a zero-copy slice of this array with the indicated offset and length.
849    ///
850    /// # Panics
851    /// Panics if `offset + length > self.len()`
852    pub fn slice(&self, offset: usize, length: usize) -> Self {
853        Self {
854            data_type: self.data_type.clone(),
855            values: self.values.slice(offset, length),
856            nulls: self.nulls.as_ref().map(|n| n.slice(offset, length)),
857        }
858    }
859
860    /// Reinterprets this array's contents as a different data type without copying
861    ///
862    /// This can be used to efficiently convert between primitive arrays with the
863    /// same underlying representation
864    ///
865    /// Note: this will not modify the underlying values, and therefore may change
866    /// the semantic values of the array, e.g. 100 milliseconds in a [`TimestampNanosecondArray`]
867    /// will become 100 seconds in a [`TimestampSecondArray`].
868    ///
869    /// For casts that preserve the semantic value, check out the
870    /// [compute kernels](https://docs.rs/arrow/latest/arrow/compute/kernels/cast/index.html).
871    ///
872    /// ```
873    /// # use arrow_array::{Int64Array, TimestampNanosecondArray};
874    /// let a = Int64Array::from_iter_values([1, 2, 3, 4]);
875    /// let b: TimestampNanosecondArray = a.reinterpret_cast();
876    /// ```
877    pub fn reinterpret_cast<K>(&self) -> PrimitiveArray<K>
878    where
879        K: ArrowPrimitiveType<Native = T::Native>,
880    {
881        PrimitiveArray::new(self.values.clone(), self.nulls.clone())
882    }
883
884    /// Applies a unary infallible function to a primitive array, producing a
885    /// new array of potentially different type.
886    ///
887    /// This is the fastest way to perform an operation on a primitive array
888    /// when the benefits of a vectorized operation outweigh the cost of
889    /// branching nulls and non-nulls.
890    ///
891    /// See also
892    /// * [`Self::unary_mut`] for in place modification.
893    /// * [`Self::try_unary`] for fallible operations.
894    /// * [`arrow::compute::binary`] for binary operations
895    ///
896    /// [`arrow::compute::binary`]: https://docs.rs/arrow/latest/arrow/compute/fn.binary.html
897    /// # Null Handling
898    ///
899    /// Applies the function for all values, including those on null slots. This
900    /// will often allow the compiler to generate faster vectorized code, but
901    /// requires that the operation must be infallible (not error/panic) for any
902    /// value of the corresponding type or this function may panic.
903    ///
904    /// # Example
905    /// ```rust
906    /// # use arrow_array::{Int32Array, Float32Array, types::Int32Type};
907    /// # fn main() {
908    /// let array = Int32Array::from(vec![Some(5), Some(7), None]);
909    /// // Create a new array with the value of applying sqrt
910    /// let c = array.unary(|x| f32::sqrt(x as f32));
911    /// assert_eq!(c, Float32Array::from(vec![Some(2.236068), Some(2.6457512), None]));
912    /// # }
913    /// ```
914    pub fn unary<F, O>(&self, op: F) -> PrimitiveArray<O>
915    where
916        O: ArrowPrimitiveType,
917        F: Fn(T::Native) -> O::Native,
918    {
919        let nulls = self.nulls().cloned();
920        // `move` puts `op`'s captures in the iterator rather than behind a reference, so the
921        // loop doesn't reload them for each value when `collect` isn't inlined
922        let values = self.values().into_iter().map(move |v| op(*v));
923        let buffer: Vec<_> = values.collect();
924        PrimitiveArray::new(buffer.into(), nulls)
925    }
926
927    /// Applies a unary and infallible function to the array in place if possible.
928    ///
929    /// # Buffer Reuse
930    ///
931    /// If the underlying buffers are not shared with other arrays,  mutates the
932    /// underlying buffer in place, without allocating.
933    ///
934    /// If the underlying buffer is shared, returns Err(self)
935    ///
936    /// # Null Handling
937    ///
938    /// See [`Self::unary`] for more information on null handling.
939    ///
940    /// # Example
941    ///
942    /// ```rust
943    /// # use arrow_array::{Int32Array, types::Int32Type};
944    /// let array = Int32Array::from(vec![Some(5), Some(7), None]);
945    /// // Apply x*2+1 to the data in place, no allocations
946    /// let c = array.unary_mut(|x| x * 2 + 1).unwrap();
947    /// assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));
948    /// ```
949    ///
950    /// # Example: modify [`ArrayRef`] in place, if not shared
951    ///
952    /// It is also possible to modify an [`ArrayRef`] if there are no other
953    /// references to the underlying buffer.
954    ///
955    /// ```rust
956    /// # use std::sync::Arc;
957    /// # use arrow_array::{Array, cast::AsArray, ArrayRef, Int32Array, PrimitiveArray, types::Int32Type};
958    /// # let array: ArrayRef = Arc::new(Int32Array::from(vec![Some(5), Some(7), None]));
959    /// // Convert to Int32Array (panic's if array.data_type is not Int32)
960    /// let a = array.as_primitive::<Int32Type>().clone();
961    /// // Try to apply x*2+1 to the data in place, fails because array is still shared
962    /// a.unary_mut(|x| x * 2 + 1).unwrap_err();
963    /// // Try again, this time dropping the last remaining reference
964    /// let a = array.as_primitive::<Int32Type>().clone();
965    /// drop(array);
966    /// // Now we can apply the operation in place
967    /// let c = a.unary_mut(|x| x * 2 + 1).unwrap();
968    /// assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));
969    /// ```
970    pub fn unary_mut<F>(self, op: F) -> Result<PrimitiveArray<T>, PrimitiveArray<T>>
971    where
972        F: Fn(T::Native) -> T::Native,
973    {
974        let mut builder = self.into_builder()?;
975        builder
976            .values_slice_mut()
977            .iter_mut()
978            .for_each(|v| *v = op(*v));
979        Ok(builder.finish())
980    }
981
982    /// Applies a unary fallible function to all valid values in a primitive
983    /// array, producing a new array of potentially different type.
984    ///
985    /// Applies `op` to only rows that are valid, which is often significantly
986    /// slower than [`Self::unary`], which should be preferred if `op` is
987    /// fallible.
988    ///
989    /// Note: LLVM is currently unable to effectively vectorize fallible operations
990    pub fn try_unary<F, O, E>(&self, op: F) -> Result<PrimitiveArray<O>, E>
991    where
992        O: ArrowPrimitiveType,
993        F: Fn(T::Native) -> Result<O::Native, E>,
994    {
995        let len = self.len();
996
997        let nulls = self.nulls().cloned();
998        let mut values = vec![O::Native::default(); len];
999        let slice = values.as_mut_slice();
1000
1001        let f = |idx| {
1002            unsafe { *slice.get_unchecked_mut(idx) = op(self.value_unchecked(idx))? };
1003            Ok::<_, E>(())
1004        };
1005
1006        match &nulls {
1007            Some(nulls) => nulls.try_for_each_valid_idx(f)?,
1008            None => (0..len).try_for_each(f)?,
1009        }
1010
1011        let values = values.into();
1012        Ok(PrimitiveArray::new(values, nulls))
1013    }
1014
1015    /// Applies a unary fallible function to all valid values in a mutable
1016    /// primitive array.
1017    ///
1018    /// # Null Handling
1019    ///
1020    /// See [`Self::try_unary`] for more information on null handling.
1021    ///
1022    /// # Buffer Reuse
1023    ///
1024    /// See [`Self::unary_mut`] for more information on buffer reuse.
1025    ///
1026    /// This returns an `Err` when the input array is shared buffer with other
1027    /// array. In the case, returned `Err` wraps input array. If the function
1028    /// encounters an error during applying on values. In the case, this returns an `Err` within
1029    /// an `Ok` which wraps the actual error.
1030    ///
1031    /// Note: LLVM is currently unable to effectively vectorize fallible operations
1032    pub fn try_unary_mut<F, E>(
1033        self,
1034        op: F,
1035    ) -> Result<Result<PrimitiveArray<T>, E>, PrimitiveArray<T>>
1036    where
1037        F: Fn(T::Native) -> Result<T::Native, E>,
1038    {
1039        let len = self.len();
1040        let null_count = self.null_count();
1041        let mut builder = self.into_builder()?;
1042
1043        let (slice, null_buffer) = builder.slices_mut();
1044
1045        let r = try_for_each_valid_idx(len, 0, null_count, null_buffer.as_deref(), |idx| {
1046            unsafe { *slice.get_unchecked_mut(idx) = op(*slice.get_unchecked(idx))? };
1047            Ok::<_, E>(())
1048        });
1049
1050        if let Err(err) = r {
1051            return Ok(Err(err));
1052        }
1053
1054        Ok(Ok(builder.finish()))
1055    }
1056
1057    /// Applies a unary and nullable function to all valid values in a primitive array
1058    ///
1059    /// Applies `op` to only rows that are valid, which is often significantly
1060    /// slower than [`Self::unary`], which should be preferred if `op` is
1061    /// fallible.
1062    ///
1063    /// Note: LLVM is currently unable to effectively vectorize fallible operations
1064    pub fn unary_opt<F, O>(&self, op: F) -> PrimitiveArray<O>
1065    where
1066        O: ArrowPrimitiveType,
1067        F: Fn(T::Native) -> Option<O::Native>,
1068    {
1069        let len = self.len();
1070        let (nulls, null_count, offset) = match self.nulls() {
1071            Some(n) => (Some(n.validity()), n.null_count(), n.offset()),
1072            None => (None, 0, 0),
1073        };
1074
1075        let mut null_builder = BooleanBufferBuilder::new(len);
1076        match nulls {
1077            Some(b) => null_builder.append_packed_range(offset..offset + len, b),
1078            None => null_builder.append_n(len, true),
1079        }
1080
1081        let mut values = vec![O::Native::default(); len];
1082        let slice = values.as_mut_slice();
1083
1084        let mut out_null_count = null_count;
1085
1086        let _ = try_for_each_valid_idx(len, offset, null_count, nulls, |idx| {
1087            match op(unsafe { self.value_unchecked(idx) }) {
1088                Some(v) => unsafe { *slice.get_unchecked_mut(idx) = v },
1089                None => {
1090                    out_null_count += 1;
1091                    null_builder.set_bit(idx, false);
1092                }
1093            }
1094            Ok::<_, ()>(())
1095        });
1096
1097        let nulls = null_builder.finish();
1098        let values = values.into();
1099        let nulls = unsafe { NullBuffer::new_unchecked(nulls, out_null_count) };
1100        PrimitiveArray::new(values, Some(nulls))
1101    }
1102
1103    /// Applies a unary infallible function to each value in an array, producing a
1104    /// new primitive array.
1105    ///
1106    /// # Null Handling
1107    ///
1108    /// See [`Self::unary`] for more information on null handling.
1109    ///
1110    /// # Example: create an [`Int16Array`] from an [`ArrayAccessor`] with item type `&[u8]`
1111    /// ```
1112    /// use arrow_array::{Array, FixedSizeBinaryArray, Int16Array};
1113    /// let input_arg = vec![ vec![1, 0], vec![2, 0], vec![3, 0] ];
1114    /// let arr = FixedSizeBinaryArray::try_from_iter(input_arg.into_iter()).unwrap();
1115    /// let c = Int16Array::from_unary(&arr, |x| i16::from_le_bytes(x[..2].try_into().unwrap()));
1116    /// assert_eq!(c, Int16Array::from(vec![Some(1i16), Some(2i16), Some(3i16)]));
1117    /// ```
1118    pub fn from_unary<U: ArrayAccessor, F>(left: U, mut op: F) -> Self
1119    where
1120        F: FnMut(U::Item) -> T::Native,
1121    {
1122        let nulls = left.logical_nulls();
1123        let buffer: Vec<_> = (0..left.len())
1124            // SAFETY: i in range 0..left.len()
1125            .map(|i| op(unsafe { left.value_unchecked(i) }))
1126            .collect();
1127        PrimitiveArray::new(buffer.into(), nulls)
1128    }
1129
1130    /// Returns a `PrimitiveBuilder` for this array, suitable for mutating values
1131    /// in place.
1132    ///
1133    /// # Buffer Reuse
1134    ///
1135    /// If the underlying data buffer has no other outstanding references, the
1136    /// buffer is used without copying.
1137    ///
1138    /// If the underlying data buffer does have outstanding references, returns
1139    /// `Err(self)`
1140    pub fn into_builder(self) -> Result<PrimitiveBuilder<T>, Self> {
1141        let len = self.len();
1142        let data_type = self.data_type.clone();
1143        let data = self.into_data();
1144        let null_bit_buffer = data.nulls().map(|b| b.inner().sliced());
1145
1146        let element_len = std::mem::size_of::<T::Native>();
1147        let buffer =
1148            data.buffers()[0].slice_with_length(data.offset() * element_len, len * element_len);
1149
1150        drop(data);
1151
1152        let try_mutable_null_buffer = match null_bit_buffer {
1153            None => Ok(None),
1154            Some(null_buffer) => {
1155                // Null buffer exists, tries to make it mutable
1156                null_buffer.into_mutable().map(Some)
1157            }
1158        };
1159
1160        let try_mutable_buffers = match try_mutable_null_buffer {
1161            Ok(mutable_null_buffer) => {
1162                // Got mutable null buffer, tries to get mutable value buffer
1163                let try_mutable_buffer = buffer.into_mutable();
1164
1165                // try_mutable_buffer.map(...).map_err(...) doesn't work as the compiler complains
1166                // mutable_null_buffer is moved into map closure.
1167                match try_mutable_buffer {
1168                    Ok(mutable_buffer) => Ok(PrimitiveBuilder::<T>::new_from_buffer(
1169                        mutable_buffer,
1170                        mutable_null_buffer,
1171                    )),
1172                    Err(buffer) => Err((buffer, mutable_null_buffer.map(|b| b.into()))),
1173                }
1174            }
1175            Err(mutable_null_buffer) => {
1176                // Unable to get mutable null buffer
1177                Err((buffer, Some(mutable_null_buffer)))
1178            }
1179        };
1180
1181        match try_mutable_buffers {
1182            Ok(builder) => Ok(builder.with_data_type(data_type)),
1183            Err((buffer, null_bit_buffer)) => {
1184                let builder = ArrayData::builder(data_type)
1185                    .len(len)
1186                    .add_buffer(buffer)
1187                    .null_bit_buffer(null_bit_buffer);
1188
1189                let array_data = unsafe { builder.build_unchecked() };
1190                let array = PrimitiveArray::<T>::from(array_data);
1191
1192                Err(array)
1193            }
1194        }
1195    }
1196}
1197
1198impl<T: ArrowPrimitiveType> From<PrimitiveArray<T>> for ArrayData {
1199    fn from(array: PrimitiveArray<T>) -> Self {
1200        /// Converts the parts of a `PrimitiveArray` into [`ArrayData`].
1201        /// Use an inner function to avoid code duplication over all
1202        /// generic callsites as the body is the same.
1203        ///
1204        /// # Safety
1205        /// The parts must come from a valid `PrimitiveArray`
1206        unsafe fn inner(
1207            data_type: DataType,
1208            len: usize,
1209            values: Buffer,
1210            nulls: Option<NullBuffer>,
1211        ) -> ArrayData {
1212            let builder = ArrayDataBuilder::new(data_type)
1213                .len(len)
1214                .nulls(nulls)
1215                .buffers(vec![values]);
1216
1217            // SAFETY: arguments are valid, per contract
1218            unsafe { builder.build_unchecked() }
1219        }
1220        let len = array.values.len();
1221        // SAFETY: the parts come from a valid PrimitiveArray
1222        unsafe { inner(array.data_type, len, array.values.into_inner(), array.nulls) }
1223    }
1224}
1225
1226/// SAFETY: Correctly implements the contract of Arrow Arrays
1227unsafe impl<T: ArrowPrimitiveType> Array for PrimitiveArray<T> {
1228    fn as_any(&self) -> &dyn Any {
1229        self
1230    }
1231
1232    fn to_data(&self) -> ArrayData {
1233        self.clone().into()
1234    }
1235
1236    fn into_data(self) -> ArrayData {
1237        self.into()
1238    }
1239
1240    fn data_type(&self) -> &DataType {
1241        &self.data_type
1242    }
1243
1244    fn slice(&self, offset: usize, length: usize) -> ArrayRef {
1245        Arc::new(self.slice(offset, length))
1246    }
1247
1248    fn len(&self) -> usize {
1249        self.values.len()
1250    }
1251
1252    fn is_empty(&self) -> bool {
1253        self.values.is_empty()
1254    }
1255
1256    fn shrink_to_fit(&mut self) {
1257        self.values.shrink_to_fit();
1258        if let Some(nulls) = &mut self.nulls {
1259            nulls.shrink_to_fit();
1260        }
1261    }
1262
1263    fn offset(&self) -> usize {
1264        0
1265    }
1266
1267    fn nulls(&self) -> Option<&NullBuffer> {
1268        self.nulls.as_ref()
1269    }
1270
1271    fn logical_null_count(&self) -> usize {
1272        self.null_count()
1273    }
1274
1275    fn get_buffer_memory_size(&self) -> usize {
1276        let mut size = self.values.inner().capacity();
1277        if let Some(n) = self.nulls.as_ref() {
1278            size += n.buffer().capacity();
1279        }
1280        size
1281    }
1282
1283    fn get_array_memory_size(&self) -> usize {
1284        std::mem::size_of::<Self>() + self.get_buffer_memory_size()
1285    }
1286
1287    #[cfg(feature = "pool")]
1288    fn claim(&self, pool: &dyn arrow_buffer::MemoryPool) {
1289        self.values.claim(pool);
1290        if let Some(nulls) = &self.nulls {
1291            nulls.claim(pool);
1292        }
1293    }
1294}
1295
1296impl<T: ArrowPrimitiveType> ArrayAccessor for &PrimitiveArray<T> {
1297    type Item = T::Native;
1298
1299    fn value(&self, index: usize) -> Self::Item {
1300        PrimitiveArray::value(self, index)
1301    }
1302
1303    #[inline]
1304    unsafe fn value_unchecked(&self, index: usize) -> Self::Item {
1305        unsafe { PrimitiveArray::value_unchecked(self, index) }
1306    }
1307}
1308
1309impl<T: ArrowTemporalType> PrimitiveArray<T>
1310where
1311    i64: From<T::Native>,
1312{
1313    /// Returns value as a chrono `NaiveDateTime`, handling time resolution
1314    ///
1315    /// If a data type cannot be converted to `NaiveDateTime`, a `None` is returned.
1316    /// A valid value is expected, thus the user should first check for validity.
1317    ///
1318    /// See notes on [`PrimitiveArray::value`] regarding nulls and panics
1319    ///
1320    /// # Panics
1321    ///
1322    /// Panics if `i >= self.len()`
1323    pub fn value_as_datetime(&self, i: usize) -> Option<NaiveDateTime> {
1324        as_datetime::<T>(i64::from(self.value(i)))
1325    }
1326
1327    /// Returns value as a chrono `NaiveDateTime`, handling time resolution with the provided tz
1328    ///
1329    /// functionally it is same as `value_as_datetime`, however it adds
1330    /// the passed tz to the to-be-returned NaiveDateTime
1331    ///
1332    /// See notes on [`PrimitiveArray::value`] regarding nulls and panics
1333    ///
1334    /// # Panics
1335    ///
1336    /// Panics if `i >= self.len()`
1337    pub fn value_as_datetime_with_tz(&self, i: usize, tz: Tz) -> Option<DateTime<Tz>> {
1338        as_datetime_with_timezone::<T>(i64::from(self.value(i)), tz)
1339    }
1340
1341    /// Returns value as a chrono `NaiveDate` by using `Self::datetime()`
1342    ///
1343    /// If a data type cannot be converted to `NaiveDate`, a `None` is returned
1344    ///
1345    /// See notes on [`PrimitiveArray::value`] regarding nulls and panics
1346    ///
1347    /// # Panics
1348    ///
1349    /// Panics if `i >= self.len()`
1350    pub fn value_as_date(&self, i: usize) -> Option<NaiveDate> {
1351        self.value_as_datetime(i).map(|datetime| datetime.date())
1352    }
1353
1354    /// Returns a value as a chrono `NaiveTime`
1355    ///
1356    /// `Date32` and `Date64` return UTC midnight as they do not have time resolution
1357    ///
1358    /// See notes on [`PrimitiveArray::value`] regarding nulls and panics
1359    ///
1360    /// # Panics
1361    ///
1362    /// Panics if `i >= self.len()`
1363    pub fn value_as_time(&self, i: usize) -> Option<NaiveTime> {
1364        as_time::<T>(i64::from(self.value(i)))
1365    }
1366
1367    /// Returns a value as a chrono `Duration`
1368    ///
1369    /// If a data type cannot be converted to `Duration`, a `None` is returned
1370    ///
1371    /// See notes on [`PrimitiveArray::value`] regarding nulls and panics
1372    ///
1373    /// # Panics
1374    ///
1375    /// Panics if `i >= self.len()`
1376    pub fn value_as_duration(&self, i: usize) -> Option<Duration> {
1377        as_duration::<T>(i64::from(self.value(i)))
1378    }
1379}
1380
1381/// Writes the `Debug` representation of a single temporal value (converted to
1382/// `i64`) of the given [`DataType`] to `f`
1383fn write_temporal_value(
1384    f: &mut std::fmt::Formatter,
1385    data_type: &DataType,
1386    v: i64,
1387) -> std::fmt::Result {
1388    match data_type {
1389        DataType::Date32 | DataType::Date64 => {
1390            match as_datetime_with_data_type(data_type, v).map(|datetime| datetime.date()) {
1391                Some(date) => write!(f, "{date:?}"),
1392                None => {
1393                    write!(
1394                        f,
1395                        "Cast error: Failed to convert {v} to temporal for {data_type}"
1396                    )
1397                }
1398            }
1399        }
1400        DataType::Time32(_) | DataType::Time64(_) => match as_time_with_data_type(data_type, v) {
1401            Some(time) => write!(f, "{time:?}"),
1402            None => {
1403                write!(
1404                    f,
1405                    "Cast error: Failed to convert {v} to temporal for {data_type}"
1406                )
1407            }
1408        },
1409        DataType::Timestamp(_, tz_string_opt) => {
1410            match tz_string_opt {
1411                // for Timestamp with TimeZone
1412                Some(tz_string) => {
1413                    match tz_string.parse::<Tz>() {
1414                        // if the time zone is valid, construct a DateTime<Tz> and format it as rfc3339
1415                        Ok(tz) => match as_datetime_with_timezone_and_data_type(data_type, v, tz) {
1416                            Some(datetime) => write!(f, "{}", datetime.to_rfc3339()),
1417                            None => write!(
1418                                f,
1419                                "Cast error: Failed to convert {v} to timestamp for {data_type}"
1420                            ),
1421                        },
1422                        // if the time zone is invalid, shows NaiveDateTime with an error message
1423                        Err(_) => match as_datetime_with_data_type(data_type, v) {
1424                            Some(datetime) => {
1425                                write!(f, "{datetime:?} (Unknown Time Zone '{tz_string}')")
1426                            }
1427                            None => write!(
1428                                f,
1429                                "Cast error: Failed to convert {v} to timestamp for {data_type}"
1430                            ),
1431                        },
1432                    }
1433                }
1434                // for Timestamp without TimeZone
1435                None => match as_datetime_with_data_type(data_type, v) {
1436                    Some(datetime) => write!(f, "{datetime:?}"),
1437                    None => write!(
1438                        f,
1439                        "Cast error: Failed to convert {v} to timestamp for {data_type}"
1440                    ),
1441                },
1442            }
1443        }
1444        _ => unreachable!("write_temporal_value called with non-temporal type {data_type}"),
1445    }
1446}
1447
1448impl<T: ArrowPrimitiveType> std::fmt::Debug for PrimitiveArray<T> {
1449    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
1450        let data_type = self.data_type();
1451
1452        write!(f, "PrimitiveArray<{data_type}>\n[\n")?;
1453        // Keep the per-value closure as small as possible: temporal formatting
1454        // is dispatched to the non-generic `write_temporal_value` so it is not
1455        // instantiated for every primitive type (see #10889)
1456        print_long_array(self, f, &mut |index, f| match data_type {
1457            DataType::Date32
1458            | DataType::Date64
1459            | DataType::Time32(_)
1460            | DataType::Time64(_)
1461            | DataType::Timestamp(_, _) => {
1462                write_temporal_value(f, data_type, self.value(index).to_i64().unwrap())
1463            }
1464            _ => std::fmt::Debug::fmt(&self.value(index), f),
1465        })?;
1466        write!(f, "]")
1467    }
1468}
1469
1470impl<'a, T: ArrowPrimitiveType> IntoIterator for &'a PrimitiveArray<T> {
1471    type Item = Option<<T as ArrowPrimitiveType>::Native>;
1472    type IntoIter = PrimitiveIter<'a, T>;
1473
1474    fn into_iter(self) -> Self::IntoIter {
1475        PrimitiveIter::<'a, T>::new(self)
1476    }
1477}
1478
1479impl<'a, T: ArrowPrimitiveType> PrimitiveArray<T> {
1480    /// constructs a new iterator
1481    pub fn iter(&'a self) -> PrimitiveIter<'a, T> {
1482        PrimitiveIter::<'a, T>::new(self)
1483    }
1484}
1485
1486/// An optional primitive value
1487///
1488/// This struct is used as an adapter when creating `PrimitiveArray` from an iterator.
1489/// `FromIterator` for `PrimitiveArray` takes an iterator where the elements can be `into`
1490/// this struct. So once implementing `From` or `Into` trait for a type, an iterator of
1491/// the type can be collected to `PrimitiveArray`.
1492#[derive(Debug)]
1493pub struct NativeAdapter<T: ArrowPrimitiveType> {
1494    /// Corresponding Rust native type if available
1495    pub native: Option<T::Native>,
1496}
1497
1498macro_rules! def_from_for_primitive {
1499    ( $ty:ident, $tt:tt) => {
1500        impl From<$tt> for NativeAdapter<$ty> {
1501            fn from(value: $tt) -> Self {
1502                NativeAdapter {
1503                    native: Some(value),
1504                }
1505            }
1506        }
1507    };
1508}
1509
1510def_from_for_primitive!(Int8Type, i8);
1511def_from_for_primitive!(Int16Type, i16);
1512def_from_for_primitive!(Int32Type, i32);
1513def_from_for_primitive!(Int64Type, i64);
1514def_from_for_primitive!(UInt8Type, u8);
1515def_from_for_primitive!(UInt16Type, u16);
1516def_from_for_primitive!(UInt32Type, u32);
1517def_from_for_primitive!(UInt64Type, u64);
1518def_from_for_primitive!(Float16Type, f16);
1519def_from_for_primitive!(Float32Type, f32);
1520def_from_for_primitive!(Float64Type, f64);
1521def_from_for_primitive!(Decimal32Type, i32);
1522def_from_for_primitive!(Decimal64Type, i64);
1523def_from_for_primitive!(Decimal128Type, i128);
1524def_from_for_primitive!(Decimal256Type, i256);
1525
1526impl<T: ArrowPrimitiveType> From<Option<<T as ArrowPrimitiveType>::Native>> for NativeAdapter<T> {
1527    fn from(value: Option<<T as ArrowPrimitiveType>::Native>) -> Self {
1528        NativeAdapter { native: value }
1529    }
1530}
1531
1532impl<T: ArrowPrimitiveType> From<&Option<<T as ArrowPrimitiveType>::Native>> for NativeAdapter<T> {
1533    fn from(value: &Option<<T as ArrowPrimitiveType>::Native>) -> Self {
1534        NativeAdapter { native: *value }
1535    }
1536}
1537
1538impl<T: ArrowPrimitiveType, Ptr: Into<NativeAdapter<T>>> FromIterator<Ptr> for PrimitiveArray<T> {
1539    fn from_iter<I: IntoIterator<Item = Ptr>>(iter: I) -> Self {
1540        let iter = iter.into_iter();
1541        let (lower, _) = iter.size_hint();
1542
1543        let mut null_builder = NullBufferBuilder::new(lower);
1544
1545        let buffer: Buffer = iter
1546            .map(|item| {
1547                if let Some(a) = item.into().native {
1548                    null_builder.append_non_null();
1549                    a
1550                } else {
1551                    null_builder.append_null();
1552                    // this ensures that null items on the buffer are not arbitrary.
1553                    // This is important because fallible operations can use null values (e.g. a vectorized "add")
1554                    // which may panic (e.g. overflow if the number on the slots happen to be very large).
1555                    T::Native::default()
1556                }
1557            })
1558            .collect();
1559
1560        let maybe_nulls = null_builder.finish();
1561        PrimitiveArray::new(ScalarBuffer::from(buffer), maybe_nulls)
1562    }
1563}
1564
1565impl<T: ArrowPrimitiveType> PrimitiveArray<T> {
1566    /// Creates a [`PrimitiveArray`] from an iterator of trusted length.
1567    /// # Safety
1568    /// The iterator must be [`TrustedLen`](https://doc.rust-lang.org/std/iter/trait.TrustedLen.html).
1569    /// I.e. that `size_hint().1` correctly reports its length.
1570    #[inline]
1571    pub unsafe fn from_trusted_len_iter<I, P>(iter: I) -> Self
1572    where
1573        P: std::borrow::Borrow<Option<<T as ArrowPrimitiveType>::Native>>,
1574        I: IntoIterator<Item = P>,
1575    {
1576        let iterator = iter.into_iter();
1577        let (_, upper) = iterator.size_hint();
1578        let len = upper.expect("trusted_len_unzip requires an upper limit");
1579
1580        let (null, buffer) = unsafe { trusted_len_unzip(iterator) };
1581
1582        let nulls = NullBuffer::from_unsliced_buffer(null, len);
1583        PrimitiveArray::new(ScalarBuffer::from(buffer), nulls)
1584    }
1585}
1586
1587// TODO: the macro is needed here because we'd get "conflicting implementations" error
1588// otherwise with both `From<Vec<T::Native>>` and `From<Vec<Option<T::Native>>>`.
1589// We should revisit this in future.
1590macro_rules! def_numeric_from_vec {
1591    ( $ty:ident ) => {
1592        impl From<Vec<<$ty as ArrowPrimitiveType>::Native>> for PrimitiveArray<$ty> {
1593            fn from(data: Vec<<$ty as ArrowPrimitiveType>::Native>) -> Self {
1594                let buffer = ScalarBuffer::from(Buffer::from_vec(data));
1595                let nulls = None;
1596                PrimitiveArray::new(buffer, nulls)
1597            }
1598        }
1599
1600        // Constructs a primitive array from a vector. Should only be used for testing.
1601        impl From<Vec<Option<<$ty as ArrowPrimitiveType>::Native>>> for PrimitiveArray<$ty> {
1602            fn from(data: Vec<Option<<$ty as ArrowPrimitiveType>::Native>>) -> Self {
1603                PrimitiveArray::from_iter(data.iter())
1604            }
1605        }
1606    };
1607}
1608
1609def_numeric_from_vec!(Int8Type);
1610def_numeric_from_vec!(Int16Type);
1611def_numeric_from_vec!(Int32Type);
1612def_numeric_from_vec!(Int64Type);
1613def_numeric_from_vec!(UInt8Type);
1614def_numeric_from_vec!(UInt16Type);
1615def_numeric_from_vec!(UInt32Type);
1616def_numeric_from_vec!(UInt64Type);
1617def_numeric_from_vec!(Float16Type);
1618def_numeric_from_vec!(Float32Type);
1619def_numeric_from_vec!(Float64Type);
1620def_numeric_from_vec!(Decimal32Type);
1621def_numeric_from_vec!(Decimal64Type);
1622def_numeric_from_vec!(Decimal128Type);
1623def_numeric_from_vec!(Decimal256Type);
1624
1625def_numeric_from_vec!(Date32Type);
1626def_numeric_from_vec!(Date64Type);
1627def_numeric_from_vec!(Time32SecondType);
1628def_numeric_from_vec!(Time32MillisecondType);
1629def_numeric_from_vec!(Time64MicrosecondType);
1630def_numeric_from_vec!(Time64NanosecondType);
1631def_numeric_from_vec!(IntervalYearMonthType);
1632def_numeric_from_vec!(IntervalDayTimeType);
1633def_numeric_from_vec!(IntervalMonthDayNanoType);
1634def_numeric_from_vec!(DurationSecondType);
1635def_numeric_from_vec!(DurationMillisecondType);
1636def_numeric_from_vec!(DurationMicrosecondType);
1637def_numeric_from_vec!(DurationNanosecondType);
1638def_numeric_from_vec!(TimestampSecondType);
1639def_numeric_from_vec!(TimestampMillisecondType);
1640def_numeric_from_vec!(TimestampMicrosecondType);
1641def_numeric_from_vec!(TimestampNanosecondType);
1642
1643impl<T: ArrowTimestampType> PrimitiveArray<T> {
1644    /// Returns the timezone of this array if any
1645    pub fn timezone(&self) -> Option<&str> {
1646        match self.data_type() {
1647            DataType::Timestamp(_, tz) => tz.as_deref(),
1648            _ => unreachable!(),
1649        }
1650    }
1651
1652    /// Construct a timestamp array with new timezone
1653    pub fn with_timezone(self, timezone: impl Into<Arc<str>>) -> Self {
1654        self.with_timezone_opt(Some(timezone.into()))
1655    }
1656
1657    /// Construct a timestamp array with UTC
1658    pub fn with_timezone_utc(self) -> Self {
1659        self.with_timezone("+00:00")
1660    }
1661
1662    /// Construct a timestamp array with an optional timezone
1663    pub fn with_timezone_opt<S: Into<Arc<str>>>(self, timezone: Option<S>) -> Self {
1664        Self {
1665            data_type: DataType::Timestamp(T::UNIT, timezone.map(Into::into)),
1666            ..self
1667        }
1668    }
1669}
1670
1671/// Constructs a `PrimitiveArray` from an array data reference.
1672impl<T: ArrowPrimitiveType> From<ArrayData> for PrimitiveArray<T> {
1673    fn from(data: ArrayData) -> Self {
1674        let (data_type, len, nulls, offset, mut buffers, _child_data) = data.into_parts();
1675
1676        Self::assert_compatible(&data_type);
1677        assert_eq!(
1678            buffers.len(),
1679            1,
1680            "PrimitiveArray data should contain a single buffer only (values buffer)"
1681        );
1682        let buffer = buffers.pop().expect("checked above");
1683
1684        let values = ScalarBuffer::new(buffer, offset, len);
1685        Self {
1686            data_type,
1687            values,
1688            nulls,
1689        }
1690    }
1691}
1692
1693impl<T: DecimalType + ArrowPrimitiveType> PrimitiveArray<T> {
1694    /// Returns a Decimal array with the same data as self, with the
1695    /// specified precision and scale.
1696    ///
1697    /// See [`validate_decimal_precision_and_scale`]
1698    pub fn with_precision_and_scale(self, precision: u8, scale: i8) -> Result<Self, ArrowError> {
1699        validate_decimal_precision_and_scale::<T>(precision, scale)?;
1700        Ok(Self {
1701            data_type: T::TYPE_CONSTRUCTOR(precision, scale),
1702            ..self
1703        })
1704    }
1705
1706    /// Validates values in this array can be properly interpreted
1707    /// with the specified precision.
1708    pub fn validate_decimal_precision(&self, precision: u8) -> Result<(), ArrowError> {
1709        if self.scale() > 0 && precision < self.scale() as u8 {
1710            return Err(ArrowError::InvalidArgumentError(format!(
1711                "Decimal precision {precision} is less than scale {}",
1712                self.scale()
1713            )));
1714        }
1715        (0..self.len()).try_for_each(|idx| {
1716            if self.is_valid(idx) {
1717                let decimal = unsafe { self.value_unchecked(idx) };
1718                T::validate_decimal_precision(decimal, precision, self.scale())
1719            } else {
1720                Ok(())
1721            }
1722        })
1723    }
1724
1725    /// Validates the Decimal Array, if the value of slot is overflow for the specified precision, and
1726    /// will be casted to Null
1727    pub fn null_if_overflow_precision(&self, precision: u8) -> Self {
1728        self.unary_opt::<_, T>(|v| T::is_valid_decimal_precision(v, precision).then_some(v))
1729            .with_data_type(self.data_type().clone())
1730    }
1731
1732    /// Returns [`Self::value`] formatted as a string
1733    pub fn value_as_string(&self, row: usize) -> String {
1734        T::format_decimal(self.value(row), self.precision(), self.scale())
1735    }
1736
1737    /// Returns the decimal precision of this array
1738    pub fn precision(&self) -> u8 {
1739        match T::BYTE_LENGTH {
1740            4 => {
1741                if let DataType::Decimal32(p, _) = self.data_type() {
1742                    *p
1743                } else {
1744                    unreachable!(
1745                        "Decimal32Array datatype is not DataType::Decimal32 but {}",
1746                        self.data_type()
1747                    )
1748                }
1749            }
1750            8 => {
1751                if let DataType::Decimal64(p, _) = self.data_type() {
1752                    *p
1753                } else {
1754                    unreachable!(
1755                        "Decimal64Array datatype is not DataType::Decimal64 but {}",
1756                        self.data_type()
1757                    )
1758                }
1759            }
1760            16 => {
1761                if let DataType::Decimal128(p, _) = self.data_type() {
1762                    *p
1763                } else {
1764                    unreachable!(
1765                        "Decimal128Array datatype is not DataType::Decimal128 but {}",
1766                        self.data_type()
1767                    )
1768                }
1769            }
1770            32 => {
1771                if let DataType::Decimal256(p, _) = self.data_type() {
1772                    *p
1773                } else {
1774                    unreachable!(
1775                        "Decimal256Array datatype is not DataType::Decimal256 but {}",
1776                        self.data_type()
1777                    )
1778                }
1779            }
1780            other => unreachable!("Unsupported byte length for decimal array {}", other),
1781        }
1782    }
1783
1784    /// Returns the decimal scale of this array
1785    pub fn scale(&self) -> i8 {
1786        match T::BYTE_LENGTH {
1787            4 => {
1788                if let DataType::Decimal32(_, s) = self.data_type() {
1789                    *s
1790                } else {
1791                    unreachable!(
1792                        "Decimal32Array datatype is not DataType::Decimal32 but {}",
1793                        self.data_type()
1794                    )
1795                }
1796            }
1797            8 => {
1798                if let DataType::Decimal64(_, s) = self.data_type() {
1799                    *s
1800                } else {
1801                    unreachable!(
1802                        "Decimal64Array datatype is not DataType::Decimal64 but {}",
1803                        self.data_type()
1804                    )
1805                }
1806            }
1807            16 => {
1808                if let DataType::Decimal128(_, s) = self.data_type() {
1809                    *s
1810                } else {
1811                    unreachable!(
1812                        "Decimal128Array datatype is not DataType::Decimal128 but {}",
1813                        self.data_type()
1814                    )
1815                }
1816            }
1817            32 => {
1818                if let DataType::Decimal256(_, s) = self.data_type() {
1819                    *s
1820                } else {
1821                    unreachable!(
1822                        "Decimal256Array datatype is not DataType::Decimal256 but {}",
1823                        self.data_type()
1824                    )
1825                }
1826            }
1827            other => unreachable!("Unsupported byte length for decimal array {}", other),
1828        }
1829    }
1830}
1831
1832#[cfg(test)]
1833mod tests {
1834    use super::*;
1835    use crate::BooleanArray;
1836    use crate::builder::{
1837        Decimal32Builder, Decimal64Builder, Decimal128Builder, Decimal256Builder,
1838    };
1839    use crate::cast::downcast_array;
1840    use arrow_buffer::{IntervalDayTime, IntervalMonthDayNano};
1841    use arrow_schema::TimeUnit;
1842
1843    #[test]
1844    fn test_primitive_array_from_vec() {
1845        let buf = Buffer::from_slice_ref([0, 1, 2, 3, 4]);
1846        let arr = Int32Array::from(vec![0, 1, 2, 3, 4]);
1847        assert_eq!(&buf, arr.values.inner());
1848        assert_eq!(5, arr.len());
1849        assert_eq!(0, arr.offset());
1850        assert_eq!(0, arr.null_count());
1851        for i in 0..5 {
1852            assert!(!arr.is_null(i));
1853            assert!(arr.is_valid(i));
1854            assert_eq!(i as i32, arr.value(i));
1855        }
1856    }
1857
1858    #[test]
1859    fn test_primitive_array_from_vec_option() {
1860        // Test building a primitive array with null values
1861        let arr = Int32Array::from(vec![Some(0), None, Some(2), None, Some(4)]);
1862        assert_eq!(5, arr.len());
1863        assert_eq!(0, arr.offset());
1864        assert_eq!(2, arr.null_count());
1865        for i in 0..5 {
1866            if i % 2 == 0 {
1867                assert!(!arr.is_null(i));
1868                assert!(arr.is_valid(i));
1869                assert_eq!(i as i32, arr.value(i));
1870            } else {
1871                assert!(arr.is_null(i));
1872                assert!(!arr.is_valid(i));
1873            }
1874        }
1875    }
1876
1877    #[test]
1878    fn test_date64_array_from_vec_option() {
1879        // Test building a primitive array with null values
1880        // we use Int32 and Int64 as a backing array, so all Int32 and Int64 conventions
1881        // work
1882        let arr: PrimitiveArray<Date64Type> =
1883            vec![Some(1550902545147), None, Some(1550902545147)].into();
1884        assert_eq!(3, arr.len());
1885        assert_eq!(0, arr.offset());
1886        assert_eq!(1, arr.null_count());
1887        for i in 0..3 {
1888            if i % 2 == 0 {
1889                assert!(!arr.is_null(i));
1890                assert!(arr.is_valid(i));
1891                assert_eq!(1550902545147, arr.value(i));
1892                // roundtrip to and from datetime
1893                assert_eq!(
1894                    1550902545147,
1895                    arr.value_as_datetime(i)
1896                        .unwrap()
1897                        .and_utc()
1898                        .timestamp_millis()
1899                );
1900            } else {
1901                assert!(arr.is_null(i));
1902                assert!(!arr.is_valid(i));
1903            }
1904        }
1905    }
1906
1907    #[test]
1908    fn test_time32_millisecond_array_from_vec() {
1909        // 1:        00:00:00.001
1910        // 37800005: 10:30:00.005
1911        // 86399210: 23:59:59.210
1912        let arr: PrimitiveArray<Time32MillisecondType> = vec![1, 37_800_005, 86_399_210].into();
1913        assert_eq!(3, arr.len());
1914        assert_eq!(0, arr.offset());
1915        assert_eq!(0, arr.null_count());
1916        let formatted = ["00:00:00.001", "10:30:00.005", "23:59:59.210"];
1917        for (i, formatted) in formatted.iter().enumerate().take(3) {
1918            // check that we can't create dates or datetimes from time instances
1919            assert_eq!(None, arr.value_as_datetime(i));
1920            assert_eq!(None, arr.value_as_date(i));
1921            let time = arr.value_as_time(i).unwrap();
1922            assert_eq!(*formatted, time.format("%H:%M:%S%.3f").to_string());
1923        }
1924    }
1925
1926    #[test]
1927    fn test_time64_nanosecond_array_from_vec() {
1928        // Test building a primitive array with null values
1929        // we use Int32 and Int64 as a backing array, so all Int32 and Int64 conventions
1930        // work
1931
1932        // 1e6:        00:00:00.001
1933        // 37800005e6: 10:30:00.005
1934        // 86399210e6: 23:59:59.210
1935        let arr: PrimitiveArray<Time64NanosecondType> =
1936            vec![1_000_000, 37_800_005_000_000, 86_399_210_000_000].into();
1937        assert_eq!(3, arr.len());
1938        assert_eq!(0, arr.offset());
1939        assert_eq!(0, arr.null_count());
1940        let formatted = ["00:00:00.001", "10:30:00.005", "23:59:59.210"];
1941        for (i, item) in formatted.iter().enumerate().take(3) {
1942            // check that we can't create dates or datetimes from time instances
1943            assert_eq!(None, arr.value_as_datetime(i));
1944            assert_eq!(None, arr.value_as_date(i));
1945            let time = arr.value_as_time(i).unwrap();
1946            assert_eq!(*item, time.format("%H:%M:%S%.3f").to_string());
1947        }
1948    }
1949
1950    #[test]
1951    fn test_interval_array_from_vec() {
1952        // intervals are currently not treated specially, but are Int32 and Int64 arrays
1953        let arr = IntervalYearMonthArray::from(vec![Some(1), None, Some(-5)]);
1954        assert_eq!(3, arr.len());
1955        assert_eq!(0, arr.offset());
1956        assert_eq!(1, arr.null_count());
1957        assert_eq!(1, arr.value(0));
1958        assert_eq!(1, arr.values()[0]);
1959        assert!(arr.is_null(1));
1960        assert_eq!(-5, arr.value(2));
1961        assert_eq!(-5, arr.values()[2]);
1962
1963        let v0 = IntervalDayTime {
1964            days: 34,
1965            milliseconds: 1,
1966        };
1967        let v2 = IntervalDayTime {
1968            days: -2,
1969            milliseconds: -5,
1970        };
1971
1972        let arr = IntervalDayTimeArray::from(vec![Some(v0), None, Some(v2)]);
1973
1974        assert_eq!(3, arr.len());
1975        assert_eq!(0, arr.offset());
1976        assert_eq!(1, arr.null_count());
1977        assert_eq!(v0, arr.value(0));
1978        assert_eq!(v0, arr.values()[0]);
1979        assert!(arr.is_null(1));
1980        assert_eq!(v2, arr.value(2));
1981        assert_eq!(v2, arr.values()[2]);
1982
1983        let v0 = IntervalMonthDayNano {
1984            months: 2,
1985            days: 34,
1986            nanoseconds: -1,
1987        };
1988        let v2 = IntervalMonthDayNano {
1989            months: -3,
1990            days: -2,
1991            nanoseconds: 4,
1992        };
1993
1994        let arr = IntervalMonthDayNanoArray::from(vec![Some(v0), None, Some(v2)]);
1995        assert_eq!(3, arr.len());
1996        assert_eq!(0, arr.offset());
1997        assert_eq!(1, arr.null_count());
1998        assert_eq!(v0, arr.value(0));
1999        assert_eq!(v0, arr.values()[0]);
2000        assert!(arr.is_null(1));
2001        assert_eq!(v2, arr.value(2));
2002        assert_eq!(v2, arr.values()[2]);
2003    }
2004
2005    #[test]
2006    fn test_duration_array_from_vec() {
2007        let arr = DurationSecondArray::from(vec![Some(1), None, Some(-5)]);
2008        assert_eq!(3, arr.len());
2009        assert_eq!(0, arr.offset());
2010        assert_eq!(1, arr.null_count());
2011        assert_eq!(1, arr.value(0));
2012        assert_eq!(1, arr.values()[0]);
2013        assert!(arr.is_null(1));
2014        assert_eq!(-5, arr.value(2));
2015        assert_eq!(-5, arr.values()[2]);
2016
2017        let arr = DurationMillisecondArray::from(vec![Some(1), None, Some(-5)]);
2018        assert_eq!(3, arr.len());
2019        assert_eq!(0, arr.offset());
2020        assert_eq!(1, arr.null_count());
2021        assert_eq!(1, arr.value(0));
2022        assert_eq!(1, arr.values()[0]);
2023        assert!(arr.is_null(1));
2024        assert_eq!(-5, arr.value(2));
2025        assert_eq!(-5, arr.values()[2]);
2026
2027        let arr = DurationMicrosecondArray::from(vec![Some(1), None, Some(-5)]);
2028        assert_eq!(3, arr.len());
2029        assert_eq!(0, arr.offset());
2030        assert_eq!(1, arr.null_count());
2031        assert_eq!(1, arr.value(0));
2032        assert_eq!(1, arr.values()[0]);
2033        assert!(arr.is_null(1));
2034        assert_eq!(-5, arr.value(2));
2035        assert_eq!(-5, arr.values()[2]);
2036
2037        let arr = DurationNanosecondArray::from(vec![Some(1), None, Some(-5)]);
2038        assert_eq!(3, arr.len());
2039        assert_eq!(0, arr.offset());
2040        assert_eq!(1, arr.null_count());
2041        assert_eq!(1, arr.value(0));
2042        assert_eq!(1, arr.values()[0]);
2043        assert!(arr.is_null(1));
2044        assert_eq!(-5, arr.value(2));
2045        assert_eq!(-5, arr.values()[2]);
2046    }
2047
2048    #[test]
2049    fn test_timestamp_array_from_vec() {
2050        let arr = TimestampSecondArray::from(vec![1, -5]);
2051        assert_eq!(2, arr.len());
2052        assert_eq!(0, arr.offset());
2053        assert_eq!(0, arr.null_count());
2054        assert_eq!(1, arr.value(0));
2055        assert_eq!(-5, arr.value(1));
2056        assert_eq!(&[1, -5], arr.values());
2057
2058        let arr = TimestampMillisecondArray::from(vec![1, -5]);
2059        assert_eq!(2, arr.len());
2060        assert_eq!(0, arr.offset());
2061        assert_eq!(0, arr.null_count());
2062        assert_eq!(1, arr.value(0));
2063        assert_eq!(-5, arr.value(1));
2064        assert_eq!(&[1, -5], arr.values());
2065
2066        let arr = TimestampMicrosecondArray::from(vec![1, -5]);
2067        assert_eq!(2, arr.len());
2068        assert_eq!(0, arr.offset());
2069        assert_eq!(0, arr.null_count());
2070        assert_eq!(1, arr.value(0));
2071        assert_eq!(-5, arr.value(1));
2072        assert_eq!(&[1, -5], arr.values());
2073
2074        let arr = TimestampNanosecondArray::from(vec![1, -5]);
2075        assert_eq!(2, arr.len());
2076        assert_eq!(0, arr.offset());
2077        assert_eq!(0, arr.null_count());
2078        assert_eq!(1, arr.value(0));
2079        assert_eq!(-5, arr.value(1));
2080        assert_eq!(&[1, -5], arr.values());
2081    }
2082
2083    #[test]
2084    fn test_primitive_array_slice() {
2085        let arr = Int32Array::from(vec![
2086            Some(0),
2087            None,
2088            Some(2),
2089            None,
2090            Some(4),
2091            Some(5),
2092            Some(6),
2093            None,
2094            None,
2095        ]);
2096        assert_eq!(9, arr.len());
2097        assert_eq!(0, arr.offset());
2098        assert_eq!(4, arr.null_count());
2099
2100        let arr2 = arr.slice(2, 5);
2101        assert_eq!(5, arr2.len());
2102        assert_eq!(1, arr2.null_count());
2103
2104        for i in 0..arr2.len() {
2105            assert_eq!(i == 1, arr2.is_null(i));
2106            assert_eq!(i != 1, arr2.is_valid(i));
2107        }
2108        let int_arr2 = arr2.as_any().downcast_ref::<Int32Array>().unwrap();
2109        assert_eq!(2, int_arr2.values()[0]);
2110        assert_eq!(&[4, 5, 6], &int_arr2.values()[2..5]);
2111
2112        let arr3 = arr2.slice(2, 3);
2113        assert_eq!(3, arr3.len());
2114        assert_eq!(0, arr3.null_count());
2115
2116        let int_arr3 = arr3.as_any().downcast_ref::<Int32Array>().unwrap();
2117        assert_eq!(&[4, 5, 6], int_arr3.values());
2118        assert_eq!(4, int_arr3.value(0));
2119        assert_eq!(5, int_arr3.value(1));
2120        assert_eq!(6, int_arr3.value(2));
2121    }
2122
2123    #[test]
2124    fn test_boolean_array_slice() {
2125        let arr = BooleanArray::from(vec![
2126            Some(true),
2127            None,
2128            Some(false),
2129            None,
2130            Some(true),
2131            Some(false),
2132            Some(true),
2133            Some(false),
2134            None,
2135            Some(true),
2136        ]);
2137
2138        assert_eq!(10, arr.len());
2139        assert_eq!(0, arr.offset());
2140        assert_eq!(3, arr.null_count());
2141
2142        let arr2 = arr.slice(3, 5);
2143        assert_eq!(5, arr2.len());
2144        assert_eq!(3, arr2.offset());
2145        assert_eq!(1, arr2.null_count());
2146
2147        let bool_arr = arr2.as_any().downcast_ref::<BooleanArray>().unwrap();
2148
2149        assert!(!bool_arr.is_valid(0));
2150
2151        assert!(bool_arr.is_valid(1));
2152        assert!(bool_arr.value(1));
2153
2154        assert!(bool_arr.is_valid(2));
2155        assert!(!bool_arr.value(2));
2156
2157        assert!(bool_arr.is_valid(3));
2158        assert!(bool_arr.value(3));
2159
2160        assert!(bool_arr.is_valid(4));
2161        assert!(!bool_arr.value(4));
2162    }
2163
2164    #[test]
2165    fn test_int32_fmt_debug() {
2166        let arr = Int32Array::from(vec![0, 1, 2, 3, 4]);
2167        assert_eq!(
2168            "PrimitiveArray<Int32>\n[\n  0,\n  1,\n  2,\n  3,\n  4,\n]",
2169            format!("{arr:?}")
2170        );
2171    }
2172
2173    #[test]
2174    fn test_fmt_debug_up_to_20_elements() {
2175        (1..=20).for_each(|i| {
2176            let values = (0..i).collect::<Vec<i16>>();
2177            let array_expected = format!(
2178                "PrimitiveArray<Int16>\n[\n{}\n]",
2179                values
2180                    .iter()
2181                    .map(|v| { format!("  {v},") })
2182                    .collect::<Vec<String>>()
2183                    .join("\n")
2184            );
2185            let array = Int16Array::from(values);
2186
2187            assert_eq!(array_expected, format!("{array:?}"));
2188        })
2189    }
2190
2191    #[test]
2192    fn test_int32_with_null_fmt_debug() {
2193        let mut builder = Int32Array::builder(3);
2194        builder.append_slice(&[0, 1]);
2195        builder.append_null();
2196        builder.append_slice(&[3, 4]);
2197        let arr = builder.finish();
2198        assert_eq!(
2199            "PrimitiveArray<Int32>\n[\n  0,\n  1,\n  null,\n  3,\n  4,\n]",
2200            format!("{arr:?}")
2201        );
2202    }
2203
2204    #[test]
2205    fn test_timestamp_fmt_debug() {
2206        let arr: PrimitiveArray<TimestampMillisecondType> =
2207            TimestampMillisecondArray::from(vec![1546214400000, 1546214400000, -1546214400000]);
2208        assert_eq!(
2209            "PrimitiveArray<Timestamp(ms)>\n[\n  2018-12-31T00:00:00,\n  2018-12-31T00:00:00,\n  1921-01-02T00:00:00,\n]",
2210            format!("{arr:?}")
2211        );
2212    }
2213
2214    #[test]
2215    fn test_timestamp_fmt_debug_out_of_range() {
2216        // Include a true null into dataset to ensure we don't write that as an error
2217        let data = Int64Array::new(
2218            vec![i64::MAX, i64::MIN, i64::MAX].into(),
2219            Some(vec![true, true, false].into()),
2220        );
2221
2222        let arr = data.reinterpret_cast::<TimestampSecondType>();
2223        assert_eq!(
2224            "PrimitiveArray<Timestamp(s)>
2225[
2226  Cast error: Failed to convert 9223372036854775807 to timestamp for Timestamp(s),
2227  Cast error: Failed to convert -9223372036854775808 to timestamp for Timestamp(s),
2228  null,
2229]",
2230            format!("{arr:?}")
2231        );
2232
2233        let arr = data.reinterpret_cast::<TimestampMillisecondType>();
2234        assert_eq!(
2235            "PrimitiveArray<Timestamp(ms)>
2236[
2237  Cast error: Failed to convert 9223372036854775807 to timestamp for Timestamp(ms),
2238  Cast error: Failed to convert -9223372036854775808 to timestamp for Timestamp(ms),
2239  null,
2240]",
2241            format!("{arr:?}")
2242        );
2243
2244        let arr = data.reinterpret_cast::<TimestampMicrosecondType>();
2245        assert_eq!(
2246            "PrimitiveArray<Timestamp(µs)>
2247[
2248  Cast error: Failed to convert 9223372036854775807 to timestamp for Timestamp(µs),
2249  Cast error: Failed to convert -9223372036854775808 to timestamp for Timestamp(µs),
2250  null,
2251]",
2252            format!("{arr:?}")
2253        );
2254
2255        // Nanoseconds always in range
2256        let arr = data.reinterpret_cast::<TimestampNanosecondType>();
2257        assert_eq!(
2258            "PrimitiveArray<Timestamp(ns)>
2259[
2260  2262-04-11T23:47:16.854775807,
2261  1677-09-21T00:12:43.145224192,
2262  null,
2263]",
2264            format!("{arr:?}")
2265        );
2266    }
2267
2268    #[test]
2269    fn test_timestamp_utc_fmt_debug() {
2270        let arr: PrimitiveArray<TimestampMillisecondType> =
2271            TimestampMillisecondArray::from(vec![1546214400000, 1546214400000, -1546214400000])
2272                .with_timezone_utc();
2273        assert_eq!(
2274            "PrimitiveArray<Timestamp(ms, \"+00:00\")>\n[\n  2018-12-31T00:00:00+00:00,\n  2018-12-31T00:00:00+00:00,\n  1921-01-02T00:00:00+00:00,\n]",
2275            format!("{arr:?}")
2276        );
2277    }
2278
2279    #[test]
2280    #[cfg(feature = "chrono-tz")]
2281    fn test_timestamp_with_named_tz_fmt_debug() {
2282        let arr: PrimitiveArray<TimestampMillisecondType> =
2283            TimestampMillisecondArray::from(vec![1546214400000, 1546214400000, -1546214400000])
2284                .with_timezone("Asia/Taipei".to_string());
2285        assert_eq!(
2286            "PrimitiveArray<Timestamp(ms, \"Asia/Taipei\")>\n[\n  2018-12-31T08:00:00+08:00,\n  2018-12-31T08:00:00+08:00,\n  1921-01-02T08:00:00+08:00,\n]",
2287            format!("{arr:?}")
2288        );
2289    }
2290
2291    #[test]
2292    #[cfg(not(feature = "chrono-tz"))]
2293    fn test_timestamp_with_named_tz_fmt_debug() {
2294        let arr: PrimitiveArray<TimestampMillisecondType> =
2295            TimestampMillisecondArray::from(vec![1546214400000, 1546214400000, -1546214400000])
2296                .with_timezone("Asia/Taipei".to_string());
2297
2298        println!("{arr:?}");
2299
2300        assert_eq!(
2301            "PrimitiveArray<Timestamp(ms, \"Asia/Taipei\")>\n[\n  2018-12-31T00:00:00 (Unknown Time Zone 'Asia/Taipei'),\n  2018-12-31T00:00:00 (Unknown Time Zone 'Asia/Taipei'),\n  1921-01-02T00:00:00 (Unknown Time Zone 'Asia/Taipei'),\n]",
2302            format!("{arr:?}")
2303        );
2304    }
2305
2306    #[test]
2307    fn test_timestamp_with_fixed_offset_tz_fmt_debug() {
2308        let arr: PrimitiveArray<TimestampMillisecondType> =
2309            TimestampMillisecondArray::from(vec![1546214400000, 1546214400000, -1546214400000])
2310                .with_timezone("+08:00".to_string());
2311        assert_eq!(
2312            "PrimitiveArray<Timestamp(ms, \"+08:00\")>\n[\n  2018-12-31T08:00:00+08:00,\n  2018-12-31T08:00:00+08:00,\n  1921-01-02T08:00:00+08:00,\n]",
2313            format!("{arr:?}")
2314        );
2315    }
2316
2317    #[test]
2318    fn test_timestamp_with_incorrect_tz_fmt_debug() {
2319        let arr: PrimitiveArray<TimestampMillisecondType> =
2320            TimestampMillisecondArray::from(vec![1546214400000, 1546214400000, -1546214400000])
2321                .with_timezone("xxx".to_string());
2322        assert_eq!(
2323            "PrimitiveArray<Timestamp(ms, \"xxx\")>\n[\n  2018-12-31T00:00:00 (Unknown Time Zone 'xxx'),\n  2018-12-31T00:00:00 (Unknown Time Zone 'xxx'),\n  1921-01-02T00:00:00 (Unknown Time Zone 'xxx'),\n]",
2324            format!("{arr:?}")
2325        );
2326    }
2327
2328    #[test]
2329    #[cfg(feature = "chrono-tz")]
2330    fn test_timestamp_with_tz_with_daylight_saving_fmt_debug() {
2331        let arr: PrimitiveArray<TimestampMillisecondType> = TimestampMillisecondArray::from(vec![
2332            1647161999000,
2333            1647162000000,
2334            1667717999000,
2335            1667718000000,
2336        ])
2337        .with_timezone("America/Denver".to_string());
2338        assert_eq!(
2339            "PrimitiveArray<Timestamp(ms, \"America/Denver\")>\n[\n  2022-03-13T01:59:59-07:00,\n  2022-03-13T03:00:00-06:00,\n  2022-11-06T00:59:59-06:00,\n  2022-11-06T01:00:00-06:00,\n]",
2340            format!("{arr:?}")
2341        );
2342    }
2343
2344    #[test]
2345    fn test_date32_fmt_debug() {
2346        let arr: PrimitiveArray<Date32Type> = vec![12356, 13548, -365].into();
2347        assert_eq!(
2348            "PrimitiveArray<Date32>\n[\n  2003-10-31,\n  2007-02-04,\n  1969-01-01,\n]",
2349            format!("{arr:?}")
2350        );
2351    }
2352
2353    #[test]
2354    fn test_time32second_fmt_debug() {
2355        let arr: PrimitiveArray<Time32SecondType> = vec![7201, 60054].into();
2356        assert_eq!(
2357            "PrimitiveArray<Time32(s)>\n[\n  02:00:01,\n  16:40:54,\n]",
2358            format!("{arr:?}")
2359        );
2360    }
2361
2362    #[test]
2363    fn test_time32second_invalid_neg() {
2364        // chrono::NaiveDatetime::from_timestamp_opt returns None while input is invalid
2365        let arr: PrimitiveArray<Time32SecondType> = vec![-7201, -60054].into();
2366        assert_eq!(
2367            "PrimitiveArray<Time32(s)>\n[\n  Cast error: Failed to convert -7201 to temporal for Time32(s),\n  Cast error: Failed to convert -60054 to temporal for Time32(s),\n]",
2368            // "PrimitiveArray<Time32(s)>\n[\n  null,\n  null,\n]",
2369            format!("{arr:?}")
2370        )
2371    }
2372
2373    #[test]
2374    fn test_primitive_array_builder() {
2375        // Test building a primitive array with ArrayData builder and offset
2376        let buf = Buffer::from_slice_ref([0i32, 1, 2, 3, 4, 5, 6]);
2377        let buf2 = buf.slice_with_length(8, 20);
2378        let data = ArrayData::builder(DataType::Int32)
2379            .len(5)
2380            .offset(2)
2381            .add_buffer(buf)
2382            .build()
2383            .unwrap();
2384        let arr = Int32Array::from(data);
2385        assert_eq!(&buf2, arr.values.inner());
2386        assert_eq!(5, arr.len());
2387        assert_eq!(0, arr.null_count());
2388        for i in 0..3 {
2389            assert_eq!((i + 2) as i32, arr.value(i));
2390        }
2391    }
2392
2393    #[test]
2394    fn test_primitive_from_iter_values() {
2395        // Test building a primitive array with from_iter_values
2396        let arr: PrimitiveArray<Int32Type> = PrimitiveArray::from_iter_values(0..10);
2397        assert_eq!(10, arr.len());
2398        assert_eq!(0, arr.null_count());
2399        for i in 0..10i32 {
2400            assert_eq!(i, arr.value(i as usize));
2401        }
2402    }
2403
2404    #[test]
2405    fn test_primitive_array_from_unbound_iter() {
2406        // iterator that doesn't declare (upper) size bound
2407        let value_iter = (0..)
2408            .scan(0usize, |pos, i| {
2409                if *pos < 10 {
2410                    *pos += 1;
2411                    Some(Some(i))
2412                } else {
2413                    // actually returns up to 10 values
2414                    None
2415                }
2416            })
2417            // limited using take()
2418            .take(100);
2419
2420        let (_, upper_size_bound) = value_iter.size_hint();
2421        // the upper bound, defined by take above, is 100
2422        assert_eq!(upper_size_bound, Some(100));
2423        let primitive_array: PrimitiveArray<Int32Type> = value_iter.collect();
2424        // but the actual number of items in the array should be 10
2425        assert_eq!(primitive_array.len(), 10);
2426    }
2427
2428    #[test]
2429    fn test_primitive_array_from_non_null_iter() {
2430        let iter = (0..10_i32).map(Some);
2431        let primitive_array = PrimitiveArray::<Int32Type>::from_iter(iter);
2432        assert_eq!(primitive_array.len(), 10);
2433        assert_eq!(primitive_array.null_count(), 0);
2434        assert!(primitive_array.nulls().is_none());
2435        assert_eq!(primitive_array.values(), &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
2436    }
2437
2438    #[test]
2439    #[should_panic(expected = "PrimitiveArray data should contain a single buffer only \
2440                               (values buffer)")]
2441    // Different error messages, so skip for now
2442    // https://github.com/apache/arrow-rs/issues/1545
2443    #[cfg(not(feature = "force_validate"))]
2444    fn test_primitive_array_invalid_buffer_len() {
2445        let buffer = Buffer::from_slice_ref([0i32, 1, 2, 3, 4]);
2446        let data = unsafe {
2447            ArrayData::builder(DataType::Int32)
2448                .add_buffer(buffer.clone())
2449                .add_buffer(buffer)
2450                .len(5)
2451                .build_unchecked()
2452        };
2453
2454        drop(Int32Array::from(data));
2455    }
2456
2457    #[test]
2458    fn test_access_array_concurrently() {
2459        let a = Int32Array::from(vec![5, 6, 7, 8, 9]);
2460        let ret = std::thread::spawn(move || a.value(3)).join();
2461
2462        assert!(ret.is_ok());
2463        assert_eq!(8, ret.ok().unwrap());
2464    }
2465
2466    #[test]
2467    fn test_primitive_array_creation() {
2468        let array1: Int8Array = [10_i8, 11, 12, 13, 14].into_iter().collect();
2469        let array2: Int8Array = [10_i8, 11, 12, 13, 14].into_iter().map(Some).collect();
2470
2471        assert_eq!(array1, array2);
2472    }
2473
2474    #[test]
2475    #[should_panic(
2476        expected = "Trying to access an element at index 4 from a PrimitiveArray of length 3"
2477    )]
2478    fn test_string_array_get_value_index_out_of_bound() {
2479        let array: Int8Array = [10_i8, 11, 12].into_iter().collect();
2480
2481        array.value(4);
2482    }
2483
2484    #[test]
2485    #[should_panic(expected = "PrimitiveArray expected data type Int64 got Int32")]
2486    fn test_from_array_data_validation() {
2487        let foo = PrimitiveArray::<Int32Type>::from_iter([1, 2, 3]);
2488        let _ = PrimitiveArray::<Int64Type>::from(foo.into_data());
2489    }
2490
2491    #[test]
2492    fn test_decimal32() {
2493        let values: Vec<_> = vec![0, 1, -1, i32::MIN, i32::MAX];
2494        let array: PrimitiveArray<Decimal32Type> =
2495            PrimitiveArray::from_iter(values.iter().copied());
2496        assert_eq!(array.values(), &values);
2497
2498        let array: PrimitiveArray<Decimal32Type> =
2499            PrimitiveArray::from_iter_values(values.iter().copied());
2500        assert_eq!(array.values(), &values);
2501
2502        let array = PrimitiveArray::<Decimal32Type>::from(values.clone());
2503        assert_eq!(array.values(), &values);
2504
2505        let array = PrimitiveArray::<Decimal32Type>::from(array.to_data());
2506        assert_eq!(array.values(), &values);
2507    }
2508
2509    #[test]
2510    fn test_decimal64() {
2511        let values: Vec<_> = vec![0, 1, -1, i64::MIN, i64::MAX];
2512        let array: PrimitiveArray<Decimal64Type> =
2513            PrimitiveArray::from_iter(values.iter().copied());
2514        assert_eq!(array.values(), &values);
2515
2516        let array: PrimitiveArray<Decimal64Type> =
2517            PrimitiveArray::from_iter_values(values.iter().copied());
2518        assert_eq!(array.values(), &values);
2519
2520        let array = PrimitiveArray::<Decimal64Type>::from(values.clone());
2521        assert_eq!(array.values(), &values);
2522
2523        let array = PrimitiveArray::<Decimal64Type>::from(array.to_data());
2524        assert_eq!(array.values(), &values);
2525    }
2526
2527    #[test]
2528    fn test_decimal128() {
2529        let values: Vec<_> = vec![0, 1, -1, i128::MIN, i128::MAX];
2530        let array: PrimitiveArray<Decimal128Type> =
2531            PrimitiveArray::from_iter(values.iter().copied());
2532        assert_eq!(array.values(), &values);
2533
2534        let array: PrimitiveArray<Decimal128Type> =
2535            PrimitiveArray::from_iter_values(values.iter().copied());
2536        assert_eq!(array.values(), &values);
2537
2538        let array = PrimitiveArray::<Decimal128Type>::from(values.clone());
2539        assert_eq!(array.values(), &values);
2540
2541        let array = PrimitiveArray::<Decimal128Type>::from(array.to_data());
2542        assert_eq!(array.values(), &values);
2543    }
2544
2545    #[test]
2546    fn test_decimal256() {
2547        let values: Vec<_> = vec![i256::ZERO, i256::ONE, i256::MINUS_ONE, i256::MIN, i256::MAX];
2548
2549        let array: PrimitiveArray<Decimal256Type> =
2550            PrimitiveArray::from_iter(values.iter().copied());
2551        assert_eq!(array.values(), &values);
2552
2553        let array: PrimitiveArray<Decimal256Type> =
2554            PrimitiveArray::from_iter_values(values.iter().copied());
2555        assert_eq!(array.values(), &values);
2556
2557        let array = PrimitiveArray::<Decimal256Type>::from(values.clone());
2558        assert_eq!(array.values(), &values);
2559
2560        let array = PrimitiveArray::<Decimal256Type>::from(array.to_data());
2561        assert_eq!(array.values(), &values);
2562    }
2563
2564    #[test]
2565    fn test_decimal_array() {
2566        // let val_8887: [u8; 16] = [192, 219, 180, 17, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
2567        // let val_neg_8887: [u8; 16] = [64, 36, 75, 238, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255];
2568        let values: [u8; 32] = [
2569            192, 219, 180, 17, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 64, 36, 75, 238, 253, 255, 255,
2570            255, 255, 255, 255, 255, 255, 255, 255, 255,
2571        ];
2572        let array_data = ArrayData::builder(DataType::Decimal128(38, 6))
2573            .len(2)
2574            .add_buffer(Buffer::from(&values))
2575            .build()
2576            .unwrap();
2577        let decimal_array = Decimal128Array::from(array_data);
2578        assert_eq!(8_887_000_000_i128, decimal_array.value(0));
2579        assert_eq!(-8_887_000_000_i128, decimal_array.value(1));
2580    }
2581
2582    #[test]
2583    fn test_decimal_append_error_value() {
2584        let mut decimal_builder = Decimal128Builder::with_capacity(10);
2585        decimal_builder.append_value(123456);
2586        decimal_builder.append_value(12345);
2587        let result = decimal_builder.finish().with_precision_and_scale(5, 3);
2588        assert!(result.is_ok());
2589        let arr = result.unwrap();
2590        assert_eq!("12.345", arr.value_as_string(1));
2591
2592        // Validate it explicitly
2593        let result = arr.validate_decimal_precision(5);
2594        let error = result.unwrap_err();
2595        assert_eq!(
2596            "Invalid argument error: 123.456 is too large to store in a Decimal128 of precision 5. Max is 99.999",
2597            error.to_string()
2598        );
2599
2600        decimal_builder = Decimal128Builder::new();
2601        decimal_builder.append_value(100);
2602        decimal_builder.append_value(99);
2603        decimal_builder.append_value(-100);
2604        decimal_builder.append_value(-99);
2605        let result = decimal_builder.finish().with_precision_and_scale(2, 1);
2606        assert!(result.is_ok());
2607        let arr = result.unwrap();
2608        assert_eq!("9.9", arr.value_as_string(1));
2609        assert_eq!("-9.9", arr.value_as_string(3));
2610
2611        // Validate it explicitly
2612        let result = arr.validate_decimal_precision(2);
2613        let error = result.unwrap_err();
2614        assert_eq!(
2615            "Invalid argument error: 10.0 is too large to store in a Decimal128 of precision 2. Max is 9.9",
2616            error.to_string()
2617        );
2618    }
2619
2620    #[test]
2621    fn test_decimal_validate_precision_with_negative_scale() {
2622        fn check<T: DecimalType>()
2623        where
2624            T::Native: From<i32>,
2625        {
2626            for scale in [i8::MIN, -2, -1, 0, 2] {
2627                let array = PrimitiveArray::<T>::from_iter(
2628                    [Some(-99), Some(0), Some(1), Some(99), None]
2629                        .into_iter()
2630                        .map(|v| v.map(T::Native::from)),
2631                )
2632                .with_precision_and_scale(2, scale)
2633                .unwrap();
2634                array.validate_decimal_precision(2).unwrap();
2635
2636                for value in [-100, 100] {
2637                    let array = PrimitiveArray::<T>::from_iter_values([T::Native::from(value)])
2638                        .with_precision_and_scale(3, scale)
2639                        .unwrap();
2640                    assert!(array.validate_decimal_precision(2).is_err());
2641                }
2642            }
2643
2644            let array = PrimitiveArray::<T>::from_iter_values([T::Native::from(100)])
2645                .with_precision_and_scale(3, -2)
2646                .unwrap();
2647            assert_eq!(
2648                array.validate_decimal_precision(2).unwrap_err().to_string(),
2649                format!(
2650                    "Invalid argument error: 10000 is too large to store in a {} of precision 2. Max is 9900",
2651                    T::PREFIX
2652                )
2653            );
2654
2655            let array = PrimitiveArray::<T>::from_iter_values([T::Native::from(0)])
2656                .with_precision_and_scale(2, 2)
2657                .unwrap();
2658            assert_eq!(
2659                array.validate_decimal_precision(1).unwrap_err().to_string(),
2660                "Invalid argument error: Decimal precision 1 is less than scale 2"
2661            );
2662        }
2663
2664        check::<Decimal32Type>();
2665        check::<Decimal64Type>();
2666        check::<Decimal128Type>();
2667        check::<Decimal256Type>();
2668    }
2669
2670    #[test]
2671    fn test_decimal_from_iter_values() {
2672        let array = Decimal128Array::from_iter_values(vec![-100, 0, 101]);
2673        assert_eq!(array.len(), 3);
2674        assert_eq!(array.data_type(), &DataType::Decimal128(38, 10));
2675        assert_eq!(-100_i128, array.value(0));
2676        assert!(!array.is_null(0));
2677        assert_eq!(0_i128, array.value(1));
2678        assert!(!array.is_null(1));
2679        assert_eq!(101_i128, array.value(2));
2680        assert!(!array.is_null(2));
2681    }
2682
2683    #[test]
2684    fn test_decimal_from_iter() {
2685        let array: Decimal128Array = vec![Some(-100), None, Some(101)].into_iter().collect();
2686        assert_eq!(array.len(), 3);
2687        assert_eq!(array.data_type(), &DataType::Decimal128(38, 10));
2688        assert_eq!(-100_i128, array.value(0));
2689        assert!(!array.is_null(0));
2690        assert!(array.is_null(1));
2691        assert_eq!(101_i128, array.value(2));
2692        assert!(!array.is_null(2));
2693    }
2694
2695    #[test]
2696    fn test_decimal_iter_sized() {
2697        let data = vec![Some(-100), None, Some(101)];
2698        let array: Decimal128Array = data.into_iter().collect();
2699        let mut iter = array.into_iter();
2700
2701        // is exact sized
2702        assert_eq!(array.len(), 3);
2703
2704        // size_hint is reported correctly
2705        assert_eq!(iter.size_hint(), (3, Some(3)));
2706        iter.next().unwrap();
2707        assert_eq!(iter.size_hint(), (2, Some(2)));
2708        iter.next().unwrap();
2709        iter.next().unwrap();
2710        assert_eq!(iter.size_hint(), (0, Some(0)));
2711        assert!(iter.next().is_none());
2712        assert_eq!(iter.size_hint(), (0, Some(0)));
2713    }
2714
2715    #[test]
2716    fn test_decimal_array_value_as_string() {
2717        let arr = [123450, -123450, 100, -100, 10, -10, 0]
2718            .into_iter()
2719            .map(Some)
2720            .collect::<Decimal128Array>()
2721            .with_precision_and_scale(6, 3)
2722            .unwrap();
2723
2724        assert_eq!("123.450", arr.value_as_string(0));
2725        assert_eq!("-123.450", arr.value_as_string(1));
2726        assert_eq!("0.100", arr.value_as_string(2));
2727        assert_eq!("-0.100", arr.value_as_string(3));
2728        assert_eq!("0.010", arr.value_as_string(4));
2729        assert_eq!("-0.010", arr.value_as_string(5));
2730        assert_eq!("0.000", arr.value_as_string(6));
2731    }
2732
2733    #[test]
2734    fn test_decimal_array_with_precision_and_scale() {
2735        let arr = Decimal128Array::from_iter_values([12345, 456, 7890, -123223423432432])
2736            .with_precision_and_scale(20, 2)
2737            .unwrap();
2738
2739        assert_eq!(arr.data_type(), &DataType::Decimal128(20, 2));
2740        assert_eq!(arr.precision(), 20);
2741        assert_eq!(arr.scale(), 2);
2742
2743        let actual: Vec<_> = (0..arr.len()).map(|i| arr.value_as_string(i)).collect();
2744        let expected = vec!["123.45", "4.56", "78.90", "-1232234234324.32"];
2745
2746        assert_eq!(actual, expected);
2747    }
2748
2749    #[test]
2750    #[should_panic(
2751        expected = "-1232234234324.32 is too small to store in a Decimal128 of precision 5. Min is -999.99"
2752    )]
2753    fn test_decimal_array_with_precision_and_scale_out_of_range() {
2754        let arr = Decimal128Array::from_iter_values([12345, 456, 7890, -123223423432432])
2755            // precision is too small to hold value
2756            .with_precision_and_scale(5, 2)
2757            .unwrap();
2758        arr.validate_decimal_precision(5).unwrap();
2759    }
2760
2761    #[test]
2762    #[should_panic(expected = "precision cannot be 0, has to be between [1, 38]")]
2763    fn test_decimal_array_with_precision_zero() {
2764        Decimal128Array::from_iter_values([12345, 456])
2765            .with_precision_and_scale(0, 2)
2766            .unwrap();
2767    }
2768
2769    #[test]
2770    #[should_panic(expected = "precision 40 is greater than max 38")]
2771    fn test_decimal_array_with_precision_and_scale_invalid_precision() {
2772        Decimal128Array::from_iter_values([12345, 456])
2773            .with_precision_and_scale(40, 2)
2774            .unwrap();
2775    }
2776
2777    #[test]
2778    #[should_panic(expected = "scale 40 is greater than max 38")]
2779    fn test_decimal_array_with_precision_and_scale_invalid_scale() {
2780        Decimal128Array::from_iter_values([12345, 456])
2781            .with_precision_and_scale(20, 40)
2782            .unwrap();
2783    }
2784
2785    #[test]
2786    #[should_panic(expected = "scale 10 is greater than precision 4")]
2787    fn test_decimal_array_with_precision_and_scale_invalid_precision_and_scale() {
2788        Decimal128Array::from_iter_values([12345, 456])
2789            .with_precision_and_scale(4, 10)
2790            .unwrap();
2791    }
2792
2793    #[test]
2794    fn test_decimal_array_set_null_if_overflow_with_precision() {
2795        let array = Decimal128Array::from(vec![Some(123456), Some(123), None, Some(123456)]);
2796        let result = array.null_if_overflow_precision(5);
2797        let expected = Decimal128Array::from(vec![None, Some(123), None, None]);
2798        assert_eq!(result, expected);
2799    }
2800
2801    #[test]
2802    fn test_null_if_overflow_precision_keeps_data_type() {
2803        let array = Decimal32Array::from(vec![99])
2804            .with_precision_and_scale(2, 1)
2805            .unwrap();
2806        assert_eq!(array.null_if_overflow_precision(2), array);
2807
2808        let array = Decimal64Array::from(vec![99])
2809            .with_precision_and_scale(2, 1)
2810            .unwrap();
2811        assert_eq!(array.null_if_overflow_precision(2), array);
2812
2813        let array = Decimal128Array::from(vec![99])
2814            .with_precision_and_scale(2, 1)
2815            .unwrap();
2816        assert_eq!(array.null_if_overflow_precision(2), array);
2817
2818        let array = Decimal256Array::from(vec![i256::from(99)])
2819            .with_precision_and_scale(2, 1)
2820            .unwrap();
2821        assert_eq!(array.null_if_overflow_precision(2), array);
2822    }
2823
2824    #[test]
2825    fn test_decimal256_iter() {
2826        let mut builder = Decimal256Builder::with_capacity(30);
2827        let decimal1 = i256::from_i128(12345);
2828        builder.append_value(decimal1);
2829
2830        builder.append_null();
2831
2832        let decimal2 = i256::from_i128(56789);
2833        builder.append_value(decimal2);
2834
2835        let array: Decimal256Array = builder.finish().with_precision_and_scale(76, 6).unwrap();
2836
2837        let collected: Vec<_> = array.iter().collect();
2838        assert_eq!(vec![Some(decimal1), None, Some(decimal2)], collected);
2839    }
2840
2841    #[test]
2842    fn test_from_iter_decimal256array() {
2843        let value1 = i256::from_i128(12345);
2844        let value2 = i256::from_i128(56789);
2845
2846        let mut array: Decimal256Array =
2847            vec![Some(value1), None, Some(value2)].into_iter().collect();
2848        array = array.with_precision_and_scale(76, 10).unwrap();
2849        assert_eq!(array.len(), 3);
2850        assert_eq!(array.data_type(), &DataType::Decimal256(76, 10));
2851        assert_eq!(value1, array.value(0));
2852        assert!(!array.is_null(0));
2853        assert!(array.is_null(1));
2854        assert_eq!(value2, array.value(2));
2855        assert!(!array.is_null(2));
2856    }
2857
2858    #[test]
2859    fn test_from_iter_decimal128array() {
2860        let mut array: Decimal128Array = vec![Some(-100), None, Some(101)].into_iter().collect();
2861        array = array.with_precision_and_scale(38, 10).unwrap();
2862        assert_eq!(array.len(), 3);
2863        assert_eq!(array.data_type(), &DataType::Decimal128(38, 10));
2864        assert_eq!(-100_i128, array.value(0));
2865        assert!(!array.is_null(0));
2866        assert!(array.is_null(1));
2867        assert_eq!(101_i128, array.value(2));
2868        assert!(!array.is_null(2));
2869    }
2870
2871    #[test]
2872    fn test_decimal64_iter() {
2873        let mut builder = Decimal64Builder::with_capacity(30);
2874        let decimal1 = 12345;
2875        builder.append_value(decimal1);
2876
2877        builder.append_null();
2878
2879        let decimal2 = 56789;
2880        builder.append_value(decimal2);
2881
2882        let array: Decimal64Array = builder.finish().with_precision_and_scale(18, 4).unwrap();
2883
2884        let collected: Vec<_> = array.iter().collect();
2885        assert_eq!(vec![Some(decimal1), None, Some(decimal2)], collected);
2886    }
2887
2888    #[test]
2889    fn test_from_iter_decimal64array() {
2890        let value1 = 12345;
2891        let value2 = 56789;
2892
2893        let mut array: Decimal64Array =
2894            vec![Some(value1), None, Some(value2)].into_iter().collect();
2895        array = array.with_precision_and_scale(18, 4).unwrap();
2896        assert_eq!(array.len(), 3);
2897        assert_eq!(array.data_type(), &DataType::Decimal64(18, 4));
2898        assert_eq!(value1, array.value(0));
2899        assert!(!array.is_null(0));
2900        assert!(array.is_null(1));
2901        assert_eq!(value2, array.value(2));
2902        assert!(!array.is_null(2));
2903    }
2904
2905    #[test]
2906    fn test_decimal32_iter() {
2907        let mut builder = Decimal32Builder::with_capacity(30);
2908        let decimal1 = 12345;
2909        builder.append_value(decimal1);
2910
2911        builder.append_null();
2912
2913        let decimal2 = 56789;
2914        builder.append_value(decimal2);
2915
2916        let array: Decimal32Array = builder.finish().with_precision_and_scale(9, 2).unwrap();
2917
2918        let collected: Vec<_> = array.iter().collect();
2919        assert_eq!(vec![Some(decimal1), None, Some(decimal2)], collected);
2920    }
2921
2922    #[test]
2923    fn test_from_iter_decimal32array() {
2924        let value1 = 12345;
2925        let value2 = 56789;
2926
2927        let mut array: Decimal32Array =
2928            vec![Some(value1), None, Some(value2)].into_iter().collect();
2929        array = array.with_precision_and_scale(9, 2).unwrap();
2930        assert_eq!(array.len(), 3);
2931        assert_eq!(array.data_type(), &DataType::Decimal32(9, 2));
2932        assert_eq!(value1, array.value(0));
2933        assert!(!array.is_null(0));
2934        assert!(array.is_null(1));
2935        assert_eq!(value2, array.value(2));
2936        assert!(!array.is_null(2));
2937    }
2938
2939    #[test]
2940    fn test_unary_opt() {
2941        let array = Int32Array::from(vec![1, 2, 3, 4, 5, 6, 7]);
2942        let r = array.unary_opt::<_, Int32Type>(|x| (x % 2 != 0).then_some(x));
2943
2944        let expected = Int32Array::from(vec![Some(1), None, Some(3), None, Some(5), None, Some(7)]);
2945        assert_eq!(r, expected);
2946
2947        let r = expected.unary_opt::<_, Int32Type>(|x| (x % 3 != 0).then_some(x));
2948        let expected = Int32Array::from(vec![Some(1), None, None, None, Some(5), None, Some(7)]);
2949        assert_eq!(r, expected);
2950    }
2951
2952    #[test]
2953    #[should_panic(
2954        expected = "Trying to access an element at index 4 from a PrimitiveArray of length 3"
2955    )]
2956    fn test_fixed_size_binary_array_get_value_index_out_of_bound() {
2957        let array = Decimal128Array::from(vec![-100, 0, 101]);
2958        array.value(4);
2959    }
2960
2961    #[test]
2962    fn test_into_builder() {
2963        let array: Int32Array = vec![1, 2, 3].into_iter().map(Some).collect();
2964
2965        let boxed: ArrayRef = Arc::new(array);
2966        let col: Int32Array = downcast_array(&boxed);
2967        drop(boxed);
2968
2969        let mut builder = col.into_builder().unwrap();
2970
2971        let slice = builder.values_slice_mut();
2972        assert_eq!(slice, &[1, 2, 3]);
2973
2974        slice[0] = 4;
2975        slice[1] = 2;
2976        slice[2] = 1;
2977
2978        let expected: Int32Array = vec![Some(4), Some(2), Some(1)].into_iter().collect();
2979
2980        let new_array = builder.finish();
2981        assert_eq!(expected, new_array);
2982    }
2983
2984    #[test]
2985    fn test_into_builder_cloned_array() {
2986        let array: Int32Array = vec![1, 2, 3].into_iter().map(Some).collect();
2987
2988        let boxed: ArrayRef = Arc::new(array);
2989
2990        let col: Int32Array = PrimitiveArray::<Int32Type>::from(boxed.to_data());
2991        let err = col.into_builder();
2992
2993        match err {
2994            Ok(_) => panic!("Should not get builder from cloned array"),
2995            Err(returned) => {
2996                let expected: Int32Array = vec![1, 2, 3].into_iter().map(Some).collect();
2997                assert_eq!(expected, returned)
2998            }
2999        }
3000    }
3001
3002    #[test]
3003    fn test_into_builder_keeps_data_type() {
3004        let array = Decimal128Array::from(vec![1, 2])
3005            .with_precision_and_scale(10, 2)
3006            .unwrap();
3007        let data_type = array.data_type().clone();
3008
3009        // Shared buffers: the array is returned
3010        let shared = array.clone();
3011        let array = array.into_builder().unwrap_err();
3012        assert_eq!(array.data_type(), &data_type);
3013        drop(shared);
3014
3015        // Unshared buffers: the buffers are reused by the builder
3016        let mut builder = array.into_builder().unwrap();
3017        builder.append_value(3);
3018        assert_eq!(builder.finish().data_type(), &data_type);
3019    }
3020
3021    #[test]
3022    fn test_into_builder_on_sliced_array() {
3023        let array: Int32Array = vec![1, 2, 3].into_iter().map(Some).collect();
3024        let slice = array.slice(1, 2);
3025        let col: Int32Array = downcast_array(&slice);
3026
3027        drop(slice);
3028
3029        col.into_builder()
3030            .expect_err("Should not build builder from sliced array");
3031    }
3032
3033    #[test]
3034    fn test_unary_mut() {
3035        let array: Int32Array = vec![1, 2, 3].into_iter().map(Some).collect();
3036
3037        let c = array.unary_mut(|x| x * 2 + 1).unwrap();
3038        let expected: Int32Array = vec![3, 5, 7].into_iter().map(Some).collect();
3039
3040        assert_eq!(expected, c);
3041
3042        let array: Int32Array = Int32Array::from(vec![Some(5), Some(7), None]);
3043        let c = array.unary_mut(|x| x * 2 + 1).unwrap();
3044        assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));
3045    }
3046
3047    #[test]
3048    #[should_panic(
3049        expected = "PrimitiveArray expected data type Interval(MonthDayNano) got Interval(DayTime)"
3050    )]
3051    fn test_invalid_interval_type() {
3052        let array = IntervalDayTimeArray::from(vec![IntervalDayTime::ZERO]);
3053        let _ = IntervalMonthDayNanoArray::from(array.into_data());
3054    }
3055
3056    #[test]
3057    fn test_timezone() {
3058        let array = TimestampNanosecondArray::from_iter_values([1, 2]);
3059        assert_eq!(array.timezone(), None);
3060
3061        let array = array.with_timezone("+02:00");
3062        assert_eq!(array.timezone(), Some("+02:00"));
3063    }
3064
3065    #[test]
3066    fn test_try_new() {
3067        Int32Array::new(vec![1, 2, 3, 4].into(), None);
3068        Int32Array::new(vec![1, 2, 3, 4].into(), Some(NullBuffer::new_null(4)));
3069
3070        let err = Int32Array::try_new(vec![1, 2, 3, 4].into(), Some(NullBuffer::new_null(3)))
3071            .unwrap_err();
3072
3073        assert_eq!(
3074            err.to_string(),
3075            "Invalid argument error: Incorrect length of null buffer for PrimitiveArray, expected 4 got 3"
3076        );
3077
3078        TimestampNanosecondArray::new(vec![1, 2, 3, 4].into(), None).with_data_type(
3079            DataType::Timestamp(TimeUnit::Nanosecond, Some("03:00".into())),
3080        );
3081    }
3082
3083    #[test]
3084    #[should_panic(expected = "PrimitiveArray expected data type Int32 got Date32")]
3085    fn test_with_data_type() {
3086        Int32Array::new(vec![1, 2, 3, 4].into(), None).with_data_type(DataType::Date32);
3087    }
3088
3089    #[test]
3090    fn test_time_32second_output() {
3091        let array: Time32SecondArray = vec![
3092            Some(-1),
3093            Some(0),
3094            Some(86_399),
3095            Some(86_400),
3096            Some(86_401),
3097            None,
3098        ]
3099        .into();
3100        let debug_str = format!("{array:?}");
3101        assert_eq!(
3102            "PrimitiveArray<Time32(s)>\n[\n  Cast error: Failed to convert -1 to temporal for Time32(s),\n  00:00:00,\n  23:59:59,\n  Cast error: Failed to convert 86400 to temporal for Time32(s),\n  Cast error: Failed to convert 86401 to temporal for Time32(s),\n  null,\n]",
3103            debug_str
3104        );
3105    }
3106
3107    #[test]
3108    fn test_time_32millisecond_debug_output() {
3109        let array: Time32MillisecondArray = vec![
3110            Some(-1),
3111            Some(0),
3112            Some(86_399_000),
3113            Some(86_400_000),
3114            Some(86_401_000),
3115            None,
3116        ]
3117        .into();
3118        let debug_str = format!("{array:?}");
3119        assert_eq!(
3120            "PrimitiveArray<Time32(ms)>\n[\n  Cast error: Failed to convert -1 to temporal for Time32(ms),\n  00:00:00,\n  23:59:59,\n  Cast error: Failed to convert 86400000 to temporal for Time32(ms),\n  Cast error: Failed to convert 86401000 to temporal for Time32(ms),\n  null,\n]",
3121            debug_str
3122        );
3123    }
3124
3125    #[test]
3126    fn test_time_64nanosecond_debug_output() {
3127        let array: Time64NanosecondArray = vec![
3128            Some(-1),
3129            Some(0),
3130            Some(86_399 * 1_000_000_000),
3131            Some(86_400 * 1_000_000_000),
3132            Some(86_401 * 1_000_000_000),
3133            None,
3134        ]
3135        .into();
3136        let debug_str = format!("{array:?}");
3137        assert_eq!(
3138            "PrimitiveArray<Time64(ns)>\n[\n  Cast error: Failed to convert -1 to temporal for Time64(ns),\n  00:00:00,\n  23:59:59,\n  Cast error: Failed to convert 86400000000000 to temporal for Time64(ns),\n  Cast error: Failed to convert 86401000000000 to temporal for Time64(ns),\n  null,\n]",
3139            debug_str
3140        );
3141    }
3142
3143    #[test]
3144    fn test_time_64microsecond_debug_output() {
3145        let array: Time64MicrosecondArray = vec![
3146            Some(-1),
3147            Some(0),
3148            Some(86_399 * 1_000_000),
3149            Some(86_400 * 1_000_000),
3150            Some(86_401 * 1_000_000),
3151            None,
3152        ]
3153        .into();
3154        let debug_str = format!("{array:?}");
3155        assert_eq!(
3156            "PrimitiveArray<Time64(µs)>\n[\n  Cast error: Failed to convert -1 to temporal for Time64(µs),\n  00:00:00,\n  23:59:59,\n  Cast error: Failed to convert 86400000000 to temporal for Time64(µs),\n  Cast error: Failed to convert 86401000000 to temporal for Time64(µs),\n  null,\n]",
3157            debug_str
3158        );
3159    }
3160
3161    #[test]
3162    fn test_primitive_with_nulls_into_builder() {
3163        let array: Int32Array = vec![
3164            Some(1),
3165            None,
3166            Some(3),
3167            Some(4),
3168            None,
3169            Some(7),
3170            None,
3171            Some(8),
3172        ]
3173        .into_iter()
3174        .collect();
3175        let _ = array.into_builder();
3176    }
3177}