diff --git a/arrow-array/src/array/boolean_array.rs b/arrow-array/src/array/boolean_array.rs index fcebf5a0f718..fe7ad85b7a05 100644 --- a/arrow-array/src/array/boolean_array.rs +++ b/arrow-array/src/array/boolean_array.rs @@ -178,6 +178,9 @@ impl BooleanArray { /// Returns the boolean value at index `i`. /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety /// This doesn't check bounds, the caller must ensure that index < self.len() pub unsafe fn value_unchecked(&self, i: usize) -> bool { @@ -185,6 +188,10 @@ impl BooleanArray { } /// Returns the boolean value at index `i`. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Panics /// Panics if index `i` is out of bounds pub fn value(&self, i: usize) -> bool { diff --git a/arrow-array/src/array/byte_array.rs b/arrow-array/src/array/byte_array.rs index 192c9654b055..2ff9e9f4f658 100644 --- a/arrow-array/src/array/byte_array.rs +++ b/arrow-array/src/array/byte_array.rs @@ -276,6 +276,10 @@ impl GenericByteArray { } /// Returns the element at index `i` + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety /// Caller is responsible for ensuring that the index is within the bounds of the array pub unsafe fn value_unchecked(&self, i: usize) -> &T::Native { @@ -304,6 +308,10 @@ impl GenericByteArray { } /// Returns the element at index `i` + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// /// # Panics /// Panics if index `i` is out of bounds. pub fn value(&self, i: usize) -> &T::Native { diff --git a/arrow-array/src/array/byte_view_array.rs b/arrow-array/src/array/byte_view_array.rs index 43ff3f76369f..7c8993d6028e 100644 --- a/arrow-array/src/array/byte_view_array.rs +++ b/arrow-array/src/array/byte_view_array.rs @@ -296,6 +296,10 @@ impl GenericByteViewArray { } /// Returns the element at index `i` + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// /// # Panics /// Panics if index `i` is out of bounds. pub fn value(&self, i: usize) -> &T::Native { @@ -312,6 +316,9 @@ impl GenericByteViewArray { /// Returns the element at index `i` without bounds checking /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety /// /// Caller is responsible for ensuring that the index is within the bounds diff --git a/arrow-array/src/array/fixed_size_binary_array.rs b/arrow-array/src/array/fixed_size_binary_array.rs index 55973a58f2cb..76d9db04704e 100644 --- a/arrow-array/src/array/fixed_size_binary_array.rs +++ b/arrow-array/src/array/fixed_size_binary_array.rs @@ -135,6 +135,10 @@ impl FixedSizeBinaryArray { } /// Returns the element at index `i` as a byte slice. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// /// # Panics /// Panics if index `i` is out of bounds. pub fn value(&self, i: usize) -> &[u8] { @@ -155,8 +159,14 @@ impl FixedSizeBinaryArray { } /// Returns the element at index `i` as a byte slice. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety - /// Caller is responsible for ensuring that the index is within the bounds of the array + /// + /// Caller is responsible for ensuring that the index is within the bounds + /// of the array pub unsafe fn value_unchecked(&self, i: usize) -> &[u8] { let offset = i + self.offset(); let pos = self.value_offset_at(offset); diff --git a/arrow-array/src/array/fixed_size_list_array.rs b/arrow-array/src/array/fixed_size_list_array.rs index f807cc88fbca..4a338591e5aa 100644 --- a/arrow-array/src/array/fixed_size_list_array.rs +++ b/arrow-array/src/array/fixed_size_list_array.rs @@ -243,6 +243,12 @@ impl FixedSizeListArray { } /// Returns ith value of this list array. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// + /// # Panics + /// Panics if index `i` is out of bounds pub fn value(&self, i: usize) -> ArrayRef { self.values .slice(self.value_offset_at(i), self.value_length() as usize) diff --git a/arrow-array/src/array/list_array.rs b/arrow-array/src/array/list_array.rs index 832a1c0a9ad8..8836b5b0f73d 100644 --- a/arrow-array/src/array/list_array.rs +++ b/arrow-array/src/array/list_array.rs @@ -327,6 +327,10 @@ impl GenericListArray { } /// Returns ith value of this list array. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety /// Caller must ensure that the index is within the array bounds pub unsafe fn value_unchecked(&self, i: usize) -> ArrayRef { @@ -336,6 +340,12 @@ impl GenericListArray { } /// Returns ith value of this list array. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// + /// # Panics + /// Panics if index `i` is out of bounds pub fn value(&self, i: usize) -> ArrayRef { let end = self.value_offsets()[i + 1].as_usize(); let start = self.value_offsets()[i].as_usize(); diff --git a/arrow-array/src/array/list_view_array.rs b/arrow-array/src/array/list_view_array.rs index a239ea1e5e73..7d66d10d263c 100644 --- a/arrow-array/src/array/list_view_array.rs +++ b/arrow-array/src/array/list_view_array.rs @@ -283,6 +283,10 @@ impl GenericListViewArray { } /// Returns ith value of this list view array. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety /// Caller must ensure that the index is within the array bounds pub unsafe fn value_unchecked(&self, i: usize) -> ArrayRef { @@ -292,6 +296,10 @@ impl GenericListViewArray { } /// Returns ith value of this list view array. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// /// # Panics /// Panics if the index is out of bounds pub fn value(&self, i: usize) -> ArrayRef { diff --git a/arrow-array/src/array/map_array.rs b/arrow-array/src/array/map_array.rs index 18a7c491aa16..9a1e04c7f1c0 100644 --- a/arrow-array/src/array/map_array.rs +++ b/arrow-array/src/array/map_array.rs @@ -185,6 +185,9 @@ impl MapArray { /// Returns ith value of this map array. /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety /// Caller must ensure that the index is within the array bounds pub unsafe fn value_unchecked(&self, i: usize) -> StructArray { @@ -197,6 +200,12 @@ impl MapArray { /// Returns ith value of this map array. /// /// This is a [`StructArray`] containing two fields + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// + /// # Panics + /// Panics if index `i` is out of bounds pub fn value(&self, i: usize) -> StructArray { let end = self.value_offsets()[i + 1] as usize; let start = self.value_offsets()[i] as usize; diff --git a/arrow-array/src/array/primitive_array.rs b/arrow-array/src/array/primitive_array.rs index 9327668824f8..42594e7a129d 100644 --- a/arrow-array/src/array/primitive_array.rs +++ b/arrow-array/src/array/primitive_array.rs @@ -720,6 +720,9 @@ impl PrimitiveArray { /// Returns the primitive value at index `i`. /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Safety /// /// caller must ensure that the passed in offset is less than the array len() @@ -729,6 +732,10 @@ impl PrimitiveArray { } /// Returns the primitive value at index `i`. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// if [`is_null`](Self::is_null) returns true for the index. + /// /// # Panics /// Panics if index `i` is out of bounds #[inline] @@ -1235,6 +1242,8 @@ where /// /// If a data type cannot be converted to `NaiveDateTime`, a `None` is returned. /// A valid value is expected, thus the user should first check for validity. + /// + /// See notes on [`PrimitiveArray::value`] regarding nulls and panics pub fn value_as_datetime(&self, i: usize) -> Option { as_datetime::(i64::from(self.value(i))) } @@ -1243,6 +1252,8 @@ where /// /// functionally it is same as `value_as_datetime`, however it adds /// the passed tz to the to-be-returned NaiveDateTime + /// + /// See notes on [`PrimitiveArray::value`] regarding nulls and panics pub fn value_as_datetime_with_tz(&self, i: usize, tz: Tz) -> Option> { as_datetime_with_timezone::(i64::from(self.value(i)), tz) } @@ -1250,6 +1261,8 @@ where /// Returns value as a chrono `NaiveDate` by using `Self::datetime()` /// /// If a data type cannot be converted to `NaiveDate`, a `None` is returned + /// + /// See notes on [`PrimitiveArray::value`] regarding nulls and panics pub fn value_as_date(&self, i: usize) -> Option { self.value_as_datetime(i).map(|datetime| datetime.date()) } @@ -1257,6 +1270,8 @@ where /// Returns a value as a chrono `NaiveTime` /// /// `Date32` and `Date64` return UTC midnight as they do not have time resolution + /// + /// See notes on [`PrimitiveArray::value`] regarding nulls and panics pub fn value_as_time(&self, i: usize) -> Option { as_time::(i64::from(self.value(i))) } @@ -1264,6 +1279,8 @@ where /// Returns a value as a chrono `Duration` /// /// If a data type cannot be converted to `Duration`, a `None` is returned + /// + /// See notes on [`PrimitiveArray::value`] regarding nulls and panics pub fn value_as_duration(&self, i: usize) -> Option { as_duration::(i64::from(self.value(i))) } diff --git a/arrow-array/src/array/union_array.rs b/arrow-array/src/array/union_array.rs index 1350cae3a38b..d105876723da 100644 --- a/arrow-array/src/array/union_array.rs +++ b/arrow-array/src/array/union_array.rs @@ -287,6 +287,10 @@ impl UnionArray { } /// Returns the array's value at index `i`. + /// + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. + /// /// # Panics /// Panics if index `i` is out of bounds pub fn value(&self, i: usize) -> ArrayRef { diff --git a/parquet-variant-compute/src/variant_array.rs b/parquet-variant-compute/src/variant_array.rs index f834df417794..e715d0a6c05a 100644 --- a/parquet-variant-compute/src/variant_array.rs +++ b/parquet-variant-compute/src/variant_array.rs @@ -146,8 +146,8 @@ impl VariantArray { /// Return the [`Variant`] instance stored at the given row /// - /// Consistently with other Arrow arrays types, this API requires you to - /// check for nulls first using [`Self::is_valid`]. + /// Note: This method does not check for nulls and the value is arbitrary + /// (but still well-defined) if [`is_null`](Self::is_null) returns true for the index. /// /// # Panics /// * if the index is out of bounds