This is an automated email from the ASF dual-hosted git repository.
Jefffrey pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new df38e646d7 docs: add `# Panics` sections across the workspace (#10656)
df38e646d7 is described below
commit df38e646d73959c53d404db3a0b3aba10444f499
Author: Emil Ernerfeldt <[email protected]>
AuthorDate: Thu Aug 13 06:10:43 2026 -0700
docs: add `# Panics` sections across the workspace (#10656)
# Which issue does this PR close?
* Part of https://github.com/apache/arrow-rs/issues/10553
# Rationale for this change
As a user, I want to avoid panics, so panics should be documented.
In a future PR I will look at all functions with `# Panics` and make
sure they have a `try_` variant that instead returns a `Result`.
# What changes are included in this PR?
Docs only, no code changes.
Adds `# Panics` to public functions that panic on bad arguments or bad
state.
Also normalizes `# Panic` to `# Panics` and converts loose "this will
panic if ..." prose into proper sections.
# Are these changes tested?
No new tests; docs only.
# Are there any user-facing changes?
Better docs!
---------
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
---
arrow-array/src/arithmetic.rs | 8 +
arrow-array/src/array/boolean_array.rs | 3 +
arrow-array/src/array/byte_array.rs | 7 +
arrow-array/src/array/byte_view_array.rs | 3 +
arrow-array/src/array/dictionary_array.rs | 9 +-
arrow-array/src/array/fixed_size_binary_array.rs | 6 +
arrow-array/src/array/fixed_size_list_array.rs | 3 +
arrow-array/src/array/list_array.rs | 6 +
arrow-array/src/array/list_view_array.rs | 11 +-
arrow-array/src/array/map_array.rs | 6 +
arrow-array/src/array/mod.rs | 17 ++
arrow-array/src/array/null_array.rs | 3 +
arrow-array/src/array/primitive_array.rs | 23 +++
arrow-array/src/array/struct_array.rs | 6 +
arrow-array/src/array/union_array.rs | 3 +
.../src/builder/fixed_size_binary_builder.rs | 4 +
arrow-array/src/builder/fixed_size_list_builder.rs | 8 +
.../src/builder/generic_byte_run_builder.rs | 6 +
arrow-array/src/builder/generic_bytes_builder.rs | 8 +
.../src/builder/generic_bytes_view_builder.rs | 10 +-
arrow-array/src/builder/generic_list_builder.rs | 10 ++
.../src/builder/generic_list_view_builder.rs | 10 ++
arrow-array/src/builder/map_builder.rs | 12 ++
arrow-array/src/builder/mod.rs | 4 +
arrow-array/src/builder/primitive_run_builder.rs | 6 +
arrow-array/src/builder/struct_builder.rs | 10 ++
arrow-array/src/cast.rs | 185 +++++++++++++++++----
arrow-array/src/ffi.rs | 2 +-
arrow-array/src/types.rs | 28 ++++
arrow-buffer/src/bigint/mod.rs | 20 ++-
arrow-buffer/src/buffer/boolean.rs | 4 +
arrow-buffer/src/buffer/immutable.rs | 4 +
arrow-buffer/src/buffer/null.rs | 16 ++
arrow-buffer/src/buffer/offset.rs | 12 +-
arrow-buffer/src/buffer/scalar.rs | 4 +
arrow-buffer/src/builder/boolean.rs | 12 ++
arrow-buffer/src/builder/null.rs | 13 ++
arrow-buffer/src/util/bit_iterator.rs | 2 +-
arrow-buffer/src/util/bit_mask.rs | 5 +
arrow-buffer/src/util/bit_util.rs | 20 +++
arrow-cast/src/base64.rs | 2 +
arrow-data/src/ffi.rs | 2 +-
arrow-data/src/transform/mod.rs | 4 +-
arrow-ord/src/cmp.rs | 4 +
arrow-row/src/lib.rs | 8 +
arrow-schema/src/ffi.rs | 12 ++
arrow-schema/src/field.rs | 2 +-
arrow/src/util/bench_util.rs | 20 +++
arrow/src/util/test_util.rs | 16 +-
parquet-variant/src/builder/object.rs | 12 +-
parquet-variant/src/variant.rs | 10 ++
parquet-variant/src/variant/list.rs | 19 ++-
parquet-variant/src/variant/metadata.rs | 13 +-
parquet-variant/src/variant/object.rs | 12 ++
parquet/src/arrow/arrow_reader/selection/mod.rs | 2 +-
parquet/src/arrow/buffer/dictionary_buffer.rs | 2 +-
parquet/src/column/reader.rs | 2 +
parquet/src/column/writer/mod.rs | 2 +
parquet/src/data_type.rs | 16 ++
parquet/src/file/metadata/mod.rs | 4 +
parquet/src/file/properties.rs | 11 ++
parquet/src/file/serialized_reader.rs | 4 +
parquet/src/schema/types.rs | 60 ++++++-
63 files changed, 703 insertions(+), 65 deletions(-)
diff --git a/arrow-array/src/arithmetic.rs b/arrow-array/src/arithmetic.rs
index 413ac0b28b..ea43ed320e 100644
--- a/arrow-array/src/arithmetic.rs
+++ b/arrow-array/src/arithmetic.rs
@@ -77,12 +77,20 @@ pub trait ArrowNativeTypeOp: ArrowNativeType {
fn div_checked(self, rhs: Self) -> Result<Self, ArrowError>;
/// Wrapping division operation
+ ///
+ /// # Panics
+ ///
+ /// Panics if `rhs` is zero for integer types
fn div_wrapping(self, rhs: Self) -> Self;
/// Checked remainder operation
fn mod_checked(self, rhs: Self) -> Result<Self, ArrowError>;
/// Wrapping remainder operation
+ ///
+ /// # Panics
+ ///
+ /// Panics if `rhs` is zero for integer types
fn mod_wrapping(self, rhs: Self) -> Self;
/// Checked negation operation
diff --git a/arrow-array/src/array/boolean_array.rs
b/arrow-array/src/array/boolean_array.rs
index 5b5dcb0daf..4b0a8304d4 100644
--- a/arrow-array/src/array/boolean_array.rs
+++ b/arrow-array/src/array/boolean_array.rs
@@ -150,6 +150,9 @@ impl BooleanArray {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
values: self.values.slice(offset, length),
diff --git a/arrow-array/src/array/byte_array.rs
b/arrow-array/src/array/byte_array.rs
index cd9d446f4d..74b9d0353b 100644
--- a/arrow-array/src/array/byte_array.rs
+++ b/arrow-array/src/array/byte_array.rs
@@ -214,6 +214,10 @@ impl<T: ByteArrayType> GenericByteArray<T> {
}
/// Creates a [`GenericByteArray`] based on an iterator of values without
nulls
+ ///
+ /// # Panics
+ /// Panics if the iterator has no upper bound on its size hint, or if the
total
+ /// length of the values exceeds `T::Offset::MAX`
pub fn from_iter_values<Ptr, I>(iter: I) -> Self
where
Ptr: AsRef<T::Native>,
@@ -359,6 +363,9 @@ impl<T: ByteArrayType> GenericByteArray<T> {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
data_type: T::DATA_TYPE,
diff --git a/arrow-array/src/array/byte_view_array.rs
b/arrow-array/src/array/byte_view_array.rs
index d1b1721034..964e7cbe34 100644
--- a/arrow-array/src/array/byte_view_array.rs
+++ b/arrow-array/src/array/byte_view_array.rs
@@ -459,6 +459,9 @@ impl<T: ByteViewType + ?Sized> GenericByteViewArray<T> {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
data_type: T::DATA_TYPE,
diff --git a/arrow-array/src/array/dictionary_array.rs
b/arrow-array/src/array/dictionary_array.rs
index 7766f952a6..0ee7710320 100644
--- a/arrow-array/src/array/dictionary_array.rs
+++ b/arrow-array/src/array/dictionary_array.rs
@@ -361,6 +361,7 @@ impl<K: ArrowDictionaryKeyType> DictionaryArray<K> {
/// returns the corresponding key (index into the `values`
/// array). Otherwise returns `None`.
///
+ /// # Panics
/// Panics if `values` is not a [`StringArray`].
pub fn lookup_key(&self, value: &str) -> Option<K::Native> {
let rd_buf: &StringArray =
self.values.as_any().downcast_ref::<StringArray>().unwrap();
@@ -402,11 +403,17 @@ impl<K: ArrowDictionaryKeyType> DictionaryArray<K> {
/// Return the value of `keys` (the dictionary key) at index `i`,
/// cast to `usize`, `None` if the value at `i` is `NULL`.
+ ///
+ /// # Panics
+ /// Panics if `i >= self.len()`
pub fn key(&self, i: usize) -> Option<usize> {
self.keys.is_valid(i).then(|| self.keys.value(i).as_usize())
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
data_type: self.data_type.clone(),
@@ -1025,7 +1032,7 @@ pub trait AnyDictionaryArray: Array {
/// The values for nulls will be arbitrary, but are guaranteed
/// to be in the range `0..self.values.len()`
///
- /// # Panic
+ /// # Panics
///
/// Panics if `values.len() == 0`
fn normalized_keys(&self) -> Vec<usize>;
diff --git a/arrow-array/src/array/fixed_size_binary_array.rs
b/arrow-array/src/array/fixed_size_binary_array.rs
index 0bfe006621..ba43ffdc90 100644
--- a/arrow-array/src/array/fixed_size_binary_array.rs
+++ b/arrow-array/src/array/fixed_size_binary_array.rs
@@ -143,6 +143,9 @@ impl FixedSizeBinaryArray {
}
/// Create a new [`Scalar`] from `value`
+ ///
+ /// # Panics
+ /// Panics if `value.as_ref().len() > i32::MAX`
pub fn new_scalar(value: impl AsRef<[u8]>) -> Scalar<Self> {
let v = value.as_ref();
let value_length =
@@ -373,6 +376,9 @@ impl FixedSizeBinaryArray {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + len > self.len()`
pub fn slice(&self, offset: usize, len: usize) -> Self {
assert!(
offset.saturating_add(len) <= self.len,
diff --git a/arrow-array/src/array/fixed_size_list_array.rs
b/arrow-array/src/array/fixed_size_list_array.rs
index 9cecc30997..84e3e0bc22 100644
--- a/arrow-array/src/array/fixed_size_list_array.rs
+++ b/arrow-array/src/array/fixed_size_list_array.rs
@@ -383,6 +383,9 @@ impl FixedSizeListArray {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + len > self.len()`
pub fn slice(&self, offset: usize, len: usize) -> Self {
assert!(
offset.saturating_add(len) <= self.len,
diff --git a/arrow-array/src/array/list_array.rs
b/arrow-array/src/array/list_array.rs
index 69c642b977..c099eecfaa 100644
--- a/arrow-array/src/array/list_array.rs
+++ b/arrow-array/src/array/list_array.rs
@@ -386,6 +386,9 @@ impl<OffsetSize: OffsetSizeTrait>
GenericListArray<OffsetSize> {
}
/// Returns the length for value at index `i`.
+ ///
+ /// # Panics
+ /// Panics if `i >= self.len()`
#[inline]
pub fn value_length(&self, i: usize) -> OffsetSize {
let offsets = self.value_offsets();
@@ -412,6 +415,9 @@ impl<OffsetSize: OffsetSizeTrait>
GenericListArray<OffsetSize> {
/// Notes: this method does *NOT* slice the underlying values array or
modify
/// the values in the offsets buffer. See [`Self::values`] and
/// [`Self::offsets`] for more information.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
data_type: self.data_type.clone(),
diff --git a/arrow-array/src/array/list_view_array.rs
b/arrow-array/src/array/list_view_array.rs
index 8e7765be70..65be4edc07 100644
--- a/arrow-array/src/array/list_view_array.rs
+++ b/arrow-array/src/array/list_view_array.rs
@@ -335,7 +335,7 @@ impl<OffsetSize: OffsetSizeTrait>
GenericListViewArray<OffsetSize> {
/// (but still well-defined) if [`is_null`](Self::is_null) returns true
for the index.
///
/// # Panics
- /// Panics if the index is out of bounds
+ /// Panics if `i >= self.len()`
pub fn value(&self, i: usize) -> ArrayRef {
let offset = self.value_offsets()[i].as_usize();
let length = self.value_sizes()[i].as_usize();
@@ -355,12 +355,18 @@ impl<OffsetSize: OffsetSizeTrait>
GenericListViewArray<OffsetSize> {
}
/// Returns the size for value at index `i`.
+ ///
+ /// # Panics
+ /// Panics if `i >= self.len()`
#[inline]
pub fn value_size(&self, i: usize) -> OffsetSize {
self.value_sizes[i]
}
/// Returns the offset for value at index `i`.
+ ///
+ /// # Panics
+ /// Panics if `i >= self.len()`
pub fn value_offset(&self, i: usize) -> OffsetSize {
self.value_offsets[i]
}
@@ -381,6 +387,9 @@ impl<OffsetSize: OffsetSizeTrait>
GenericListViewArray<OffsetSize> {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
data_type: self.data_type.clone(),
diff --git a/arrow-array/src/array/map_array.rs
b/arrow-array/src/array/map_array.rs
index 7f90f0ffd2..1254ac32bf 100644
--- a/arrow-array/src/array/map_array.rs
+++ b/arrow-array/src/array/map_array.rs
@@ -266,6 +266,9 @@ impl MapArray {
}
/// Returns the length for value at index `i`.
+ ///
+ /// # Panics
+ /// Panics if `i >= self.len()`
#[inline]
pub fn value_length(&self, i: usize) -> i32 {
let offsets = self.value_offsets();
@@ -273,6 +276,9 @@ impl MapArray {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
data_type: self.data_type.clone(),
diff --git a/arrow-array/src/array/mod.rs b/arrow-array/src/array/mod.rs
index 589044fdd8..b3eb5eeaf2 100644
--- a/arrow-array/src/array/mod.rs
+++ b/arrow-array/src/array/mod.rs
@@ -157,6 +157,9 @@ pub unsafe trait Array: std::fmt::Debug + Send + Sync {
///
/// assert_eq!(&array_slice, &Int32Array::from(vec![2, 3, 4]));
/// ```
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
fn slice(&self, offset: usize, length: usize) -> ArrayRef;
/// Returns the length (i.e., number of elements) of this array.
@@ -265,6 +268,13 @@ pub unsafe trait Array: std::fmt::Debug + Send + Sync {
/// let array = NullArray::new(1);
/// assert_eq!(array.is_null(0), false);
/// ```
+ ///
+ /// # Panics
+ ///
+ /// Panics if `index >= self.len()`.
+ ///
+ /// Note: arrays without a null buffer currently return `false` instead of
+ /// panicking, but callers must not rely on this.
fn is_null(&self, index: usize) -> bool {
self.nulls().is_some_and(|n| n.is_null(index))
}
@@ -282,6 +292,13 @@ pub unsafe trait Array: std::fmt::Debug + Send + Sync {
/// assert_eq!(array.is_valid(0), true);
/// assert_eq!(array.is_valid(1), false);
/// ```
+ ///
+ /// # Panics
+ ///
+ /// Panics if `index >= self.len()`.
+ ///
+ /// Note: arrays without a null buffer currently return `true` instead of
+ /// panicking, but callers must not rely on this.
fn is_valid(&self, index: usize) -> bool {
!self.is_null(index)
}
diff --git a/arrow-array/src/array/null_array.rs
b/arrow-array/src/array/null_array.rs
index d7c005b0a5..feced56a14 100644
--- a/arrow-array/src/array/null_array.rs
+++ b/arrow-array/src/array/null_array.rs
@@ -58,6 +58,9 @@ impl NullArray {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + len > self.len()`
pub fn slice(&self, offset: usize, len: usize) -> Self {
assert!(
offset.saturating_add(len) <= self.len,
diff --git a/arrow-array/src/array/primitive_array.rs
b/arrow-array/src/array/primitive_array.rs
index 321d2cb27a..68b404e32b 100644
--- a/arrow-array/src/array/primitive_array.rs
+++ b/arrow-array/src/array/primitive_array.rs
@@ -848,6 +848,9 @@ impl<T: ArrowPrimitiveType> PrimitiveArray<T> {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
Self {
data_type: self.data_type.clone(),
@@ -1297,6 +1300,10 @@ where
/// A valid value is expected, thus the user should first check for
validity.
///
/// See notes on [`PrimitiveArray::value`] regarding nulls and panics
+ ///
+ /// # Panics
+ ///
+ /// Panics if `i >= self.len()`
pub fn value_as_datetime(&self, i: usize) -> Option<NaiveDateTime> {
as_datetime::<T>(i64::from(self.value(i)))
}
@@ -1307,6 +1314,10 @@ where
/// the passed tz to the to-be-returned NaiveDateTime
///
/// See notes on [`PrimitiveArray::value`] regarding nulls and panics
+ ///
+ /// # Panics
+ ///
+ /// Panics if `i >= self.len()`
pub fn value_as_datetime_with_tz(&self, i: usize, tz: Tz) ->
Option<DateTime<Tz>> {
as_datetime_with_timezone::<T>(i64::from(self.value(i)), tz)
}
@@ -1316,6 +1327,10 @@ where
/// If a data type cannot be converted to `NaiveDate`, a `None` is returned
///
/// See notes on [`PrimitiveArray::value`] regarding nulls and panics
+ ///
+ /// # Panics
+ ///
+ /// Panics if `i >= self.len()`
pub fn value_as_date(&self, i: usize) -> Option<NaiveDate> {
self.value_as_datetime(i).map(|datetime| datetime.date())
}
@@ -1325,6 +1340,10 @@ where
/// `Date32` and `Date64` return UTC midnight as they do not have time
resolution
///
/// See notes on [`PrimitiveArray::value`] regarding nulls and panics
+ ///
+ /// # Panics
+ ///
+ /// Panics if `i >= self.len()`
pub fn value_as_time(&self, i: usize) -> Option<NaiveTime> {
as_time::<T>(i64::from(self.value(i)))
}
@@ -1334,6 +1353,10 @@ where
/// If a data type cannot be converted to `Duration`, a `None` is returned
///
/// See notes on [`PrimitiveArray::value`] regarding nulls and panics
+ ///
+ /// # Panics
+ ///
+ /// Panics if `i >= self.len()`
pub fn value_as_duration(&self, i: usize) -> Option<Duration> {
as_duration::<T>(i64::from(self.value(i)))
}
diff --git a/arrow-array/src/array/struct_array.rs
b/arrow-array/src/array/struct_array.rs
index 126a3ff4b2..95907d3246 100644
--- a/arrow-array/src/array/struct_array.rs
+++ b/arrow-array/src/array/struct_array.rs
@@ -280,6 +280,9 @@ impl StructArray {
}
/// Returns the field at `pos`.
+ ///
+ /// # Panics
+ /// Panics if `pos` is out of bounds
pub fn column(&self, pos: usize) -> &ArrayRef {
&self.fields[pos]
}
@@ -339,6 +342,9 @@ impl StructArray {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + len > self.len()`
pub fn slice(&self, offset: usize, len: usize) -> Self {
assert!(
offset.saturating_add(len) <= self.len,
diff --git a/arrow-array/src/array/union_array.rs
b/arrow-array/src/array/union_array.rs
index 9c57a702b4..dbba6b9545 100644
--- a/arrow-array/src/array/union_array.rs
+++ b/arrow-array/src/array/union_array.rs
@@ -328,6 +328,9 @@ impl UnionArray {
}
/// Returns a zero-copy slice of this array with the indicated offset and
length.
+ ///
+ /// # Panics
+ /// Panics if `offset + length > self.len()`
pub fn slice(&self, offset: usize, length: usize) -> Self {
let (offsets, fields) = match self.offsets.as_ref() {
// If dense union, slice offsets
diff --git a/arrow-array/src/builder/fixed_size_binary_builder.rs
b/arrow-array/src/builder/fixed_size_binary_builder.rs
index b033ed0ff3..97fab0b55b 100644
--- a/arrow-array/src/builder/fixed_size_binary_builder.rs
+++ b/arrow-array/src/builder/fixed_size_binary_builder.rs
@@ -56,6 +56,10 @@ impl FixedSizeBinaryBuilder {
/// Creates a new [`FixedSizeBinaryBuilder`], `capacity` is the number of
byte slices
/// that can be appended without reallocating
+ ///
+ /// # Panics
+ ///
+ /// Panics if `byte_width < 0`
pub fn with_capacity(capacity: usize, byte_width: i32) -> Self {
assert!(
byte_width >= 0,
diff --git a/arrow-array/src/builder/fixed_size_list_builder.rs
b/arrow-array/src/builder/fixed_size_list_builder.rs
index 1ad2f7aeaa..67608983bb 100644
--- a/arrow-array/src/builder/fixed_size_list_builder.rs
+++ b/arrow-array/src/builder/fixed_size_list_builder.rs
@@ -170,6 +170,10 @@ where
}
/// Builds the [`FixedSizeListBuilder`] and reset this builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the length of the child array is not `self.len() *
value_length`
pub fn finish(&mut self) -> FixedSizeListArray {
let len = self.len();
let values = self.values_builder.finish();
@@ -193,6 +197,10 @@ where
}
/// Builds the [`FixedSizeListBuilder`] without resetting the builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the length of the child array is not `self.len() *
value_length`
pub fn finish_cloned(&self) -> FixedSizeListArray {
let len = self.len();
let values = self.values_builder.finish_cloned();
diff --git a/arrow-array/src/builder/generic_byte_run_builder.rs
b/arrow-array/src/builder/generic_byte_run_builder.rs
index 18544f7e75..ffa548028c 100644
--- a/arrow-array/src/builder/generic_byte_run_builder.rs
+++ b/arrow-array/src/builder/generic_byte_run_builder.rs
@@ -194,6 +194,9 @@ where
}
/// Creates the RunArray and resets the builder.
+ ///
+ /// # Panics
+ ///
/// Panics if RunArray cannot be built.
pub fn finish(&mut self) -> RunArray<R> {
// write the last run end to the array.
@@ -212,6 +215,9 @@ where
}
/// Creates the RunArray and without resetting the builder.
+ ///
+ /// # Panics
+ ///
/// Panics if RunArray cannot be built.
pub fn finish_cloned(&self) -> RunArray<R> {
let mut run_ends_array = self.run_ends_builder.finish_cloned();
diff --git a/arrow-array/src/builder/generic_bytes_builder.rs
b/arrow-array/src/builder/generic_bytes_builder.rs
index f449219c6b..85205dab69 100644
--- a/arrow-array/src/builder/generic_bytes_builder.rs
+++ b/arrow-array/src/builder/generic_bytes_builder.rs
@@ -113,6 +113,10 @@ impl<T: ByteArrayType> GenericByteBuilder<T> {
/// Appends a value of type `T` into the builder `n` times.
///
/// See [`Self::append_value`] for more panic information.
+ ///
+ /// # Panics
+ ///
+ /// Panics for the same reasons as [`Self::append_value`]
#[inline]
pub fn append_value_n(&mut self, value: impl AsRef<T::Native>, n: usize) {
let bytes: &[u8] = value.as_ref().as_ref();
@@ -131,6 +135,10 @@ impl<T: ByteArrayType> GenericByteBuilder<T> {
/// - A `Some` value will append the value.
///
/// See [`Self::append_value`] for more panic information.
+ ///
+ /// # Panics
+ ///
+ /// Panics for the same reasons as [`Self::append_value`]
#[inline]
pub fn append_option(&mut self, value: Option<impl AsRef<T::Native>>) {
match value {
diff --git a/arrow-array/src/builder/generic_bytes_view_builder.rs
b/arrow-array/src/builder/generic_bytes_view_builder.rs
index 4886d56e7f..cb7ecf85eb 100644
--- a/arrow-array/src/builder/generic_bytes_view_builder.rs
+++ b/arrow-array/src/builder/generic_bytes_view_builder.rs
@@ -191,6 +191,10 @@ impl<T: ByteViewType + ?Sized> GenericByteViewBuilder<T> {
/// let expected = &["hello", "world", "bingo", "bongo",
"helloworldbingo"];
/// assert_eq!(actual, expected);
/// ```
+ ///
+ /// # Panics
+ ///
+ /// Panics if `buffer.len() >= u32::MAX`
pub fn append_block(&mut self, buffer: Buffer) -> u32 {
assert!(buffer.len() < u32::MAX as usize);
@@ -296,8 +300,12 @@ impl<T: ByteViewType + ?Sized> GenericByteViewBuilder<T> {
}
/// Returns the value at the given index
+ ///
/// Useful if we want to know what value has been inserted to the builder
- /// The index has to be smaller than `self.len()`, otherwise it will panic
+ ///
+ /// # Panics
+ ///
+ /// Panics if `index >= self.len()`
pub fn get_value(&self, index: usize) -> &[u8] {
let view = self.views_buffer.as_slice().get(index).unwrap();
let len = *view as u32;
diff --git a/arrow-array/src/builder/generic_list_builder.rs
b/arrow-array/src/builder/generic_list_builder.rs
index f93625e8eb..1dd2a452c7 100644
--- a/arrow-array/src/builder/generic_list_builder.rs
+++ b/arrow-array/src/builder/generic_list_builder.rs
@@ -299,6 +299,11 @@ where
}
/// Builds the [`GenericListArray`] and reset this builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the field set with [`Self::with_field`] does not match the
data type
+ /// of the values builder
pub fn finish(&mut self) -> GenericListArray<OffsetSize> {
let values = self.values_builder.finish();
let nulls = self.null_buffer_builder.finish();
@@ -317,6 +322,11 @@ where
}
/// Builds the [`GenericListArray`] without resetting the builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the field set with [`Self::with_field`] does not match the
data type
+ /// of the values builder
pub fn finish_cloned(&self) -> GenericListArray<OffsetSize> {
let values = self.values_builder.finish_cloned();
let nulls = self.null_buffer_builder.finish_cloned();
diff --git a/arrow-array/src/builder/generic_list_view_builder.rs
b/arrow-array/src/builder/generic_list_view_builder.rs
index 4f9bd64c5d..925ea80940 100644
--- a/arrow-array/src/builder/generic_list_view_builder.rs
+++ b/arrow-array/src/builder/generic_list_view_builder.rs
@@ -183,6 +183,11 @@ where
}
/// Builds the [`GenericListViewArray`] and reset this builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the field set with [`Self::with_field`] does not match the
data type
+ /// of the values builder
pub fn finish(&mut self) -> GenericListViewArray<OffsetSize> {
let values = self.values_builder.finish();
let nulls = self.null_buffer_builder.finish();
@@ -201,6 +206,11 @@ where
}
/// Builds the [`GenericListViewArray`] without resetting the builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the field set with [`Self::with_field`] does not match the
data type
+ /// of the values builder
pub fn finish_cloned(&self) -> GenericListViewArray<OffsetSize> {
let values = self.values_builder.finish_cloned();
let nulls = self.null_buffer_builder.finish_cloned();
diff --git a/arrow-array/src/builder/map_builder.rs
b/arrow-array/src/builder/map_builder.rs
index d1862af4e8..9306c856f3 100644
--- a/arrow-array/src/builder/map_builder.rs
+++ b/arrow-array/src/builder/map_builder.rs
@@ -191,6 +191,12 @@ impl<K: ArrayBuilder, V: ArrayBuilder> MapBuilder<K, V> {
}
/// Builds the [`MapArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if the fields set with [`Self::with_keys_field`] or
+ /// [`Self::with_values_field`] do not match the data types of the key and
value
+ /// builders, or if the keys contain nulls
pub fn finish(&mut self) -> MapArray {
let len = self.len();
// Build the keys
@@ -204,6 +210,12 @@ impl<K: ArrayBuilder, V: ArrayBuilder> MapBuilder<K, V> {
}
/// Builds the [`MapArray`] without resetting the builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the fields set with [`Self::with_keys_field`] or
+ /// [`Self::with_values_field`] do not match the data types of the key and
value
+ /// builders, or if the keys contain nulls
pub fn finish_cloned(&self) -> MapArray {
let len = self.len();
// Build the keys
diff --git a/arrow-array/src/builder/mod.rs b/arrow-array/src/builder/mod.rs
index 7feb1b4d2b..813f028efb 100644
--- a/arrow-array/src/builder/mod.rs
+++ b/arrow-array/src/builder/mod.rs
@@ -445,6 +445,10 @@ pub type LargeStringBuilder = GenericStringBuilder<i64>;
///
/// See comments on [StructBuilder] for retrieving collection builders built by
/// make_builder.
+///
+/// # Panics
+///
+/// Panics if `datatype` is not supported, see [`ArrayBuilder`] implementations
pub fn make_builder(datatype: &DataType, capacity: usize) -> Box<dyn
ArrayBuilder> {
use crate::builder::*;
match datatype {
diff --git a/arrow-array/src/builder/primitive_run_builder.rs
b/arrow-array/src/builder/primitive_run_builder.rs
index 8febc29294..71fcf87475 100644
--- a/arrow-array/src/builder/primitive_run_builder.rs
+++ b/arrow-array/src/builder/primitive_run_builder.rs
@@ -192,6 +192,9 @@ where
}
/// Creates the RunArray and resets the builder.
+ ///
+ /// # Panics
+ ///
/// Panics if RunArray cannot be built.
pub fn finish(&mut self) -> RunArray<R> {
// write the last run end to the array.
@@ -208,6 +211,9 @@ where
}
/// Creates the RunArray and without resetting the builder.
+ ///
+ /// # Panics
+ ///
/// Panics if RunArray cannot be built.
pub fn finish_cloned(&self) -> RunArray<R> {
let mut run_ends_array = self.run_ends_builder.finish_cloned();
diff --git a/arrow-array/src/builder/struct_builder.rs
b/arrow-array/src/builder/struct_builder.rs
index 3d773864f5..e8af63cb2d 100644
--- a/arrow-array/src/builder/struct_builder.rs
+++ b/arrow-array/src/builder/struct_builder.rs
@@ -236,6 +236,11 @@ impl StructBuilder {
}
/// Builds the `StructArray` and reset this builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the number of fields is not equal to the number of field
builders, or
+ /// if the field builders do not all have length `self.len()`
pub fn finish(&mut self) -> StructArray {
self.validate_content();
if self.fields.is_empty() {
@@ -248,6 +253,11 @@ impl StructBuilder {
}
/// Builds the `StructArray` without resetting the builder.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the number of fields is not equal to the number of field
builders, or
+ /// if the field builders do not all have length `self.len()`
pub fn finish_cloned(&self) -> StructArray {
self.validate_content();
diff --git a/arrow-array/src/cast.rs b/arrow-array/src/cast.rs
index d30de5906f..1c8a14ccb0 100644
--- a/arrow-array/src/cast.rs
+++ b/arrow-array/src/cast.rs
@@ -477,7 +477,7 @@ macro_rules! downcast_primitive_array {
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`], to
-/// [`PrimitiveArray<T>`], panic'ing on failure.
+/// [`PrimitiveArray<T>`].
///
/// # Example
///
@@ -501,6 +501,10 @@ macro_rules! downcast_primitive_array {
/// .downcast_ref::<Int32Array>()
/// .unwrap();
/// ```
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`PrimitiveArray<T>`]
pub fn as_primitive_array<T>(arr: &dyn Array) -> &PrimitiveArray<T>
where
T: ArrowPrimitiveType,
@@ -573,7 +577,7 @@ macro_rules! downcast_dictionary_array {
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`DictionaryArray<T>`], panic'ing on failure.
+/// [`DictionaryArray<T>`].
///
/// # Example
///
@@ -586,6 +590,10 @@ macro_rules! downcast_dictionary_array {
/// let arr: ArrayRef = std::sync::Arc::new(arr);
/// let dict_array: &DictionaryArray<Int32Type> =
as_dictionary_array::<Int32Type>(&arr);
/// ```
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`DictionaryArray<T>`]
pub fn as_dictionary_array<T>(arr: &dyn Array) -> &DictionaryArray<T>
where
T: ArrowDictionaryKeyType,
@@ -596,7 +604,7 @@ where
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`RunArray<T>`], panic'ing on failure.
+/// [`RunArray<T>`].
///
/// # Example
///
@@ -609,6 +617,10 @@ where
/// let arr: ArrayRef = std::sync::Arc::new(arr);
/// let run_array: &RunArray<Int32Type> = as_run_array::<Int32Type>(&arr);
/// ```
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`RunArray<T>`]
pub fn as_run_array<T>(arr: &dyn Array) -> &RunArray<T>
where
T: RunEndIndexType,
@@ -681,7 +693,11 @@ macro_rules! downcast_run_array {
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`GenericListArray<T>`], panicking on failure.
+/// [`GenericListArray<T>`].
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`GenericListArray<T>`]
pub fn as_generic_list_array<S: OffsetSizeTrait>(arr: &dyn Array) ->
&GenericListArray<S> {
arr.as_any()
.downcast_ref::<GenericListArray<S>>()
@@ -689,14 +705,22 @@ pub fn as_generic_list_array<S: OffsetSizeTrait>(arr:
&dyn Array) -> &GenericLis
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`ListArray`], panicking on failure.
+/// [`ListArray`].
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`ListArray`]
#[inline]
pub fn as_list_array(arr: &dyn Array) -> &ListArray {
as_generic_list_array::<i32>(arr)
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`FixedSizeListArray`], panicking on failure.
+/// [`FixedSizeListArray`].
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`FixedSizeListArray`]
#[inline]
pub fn as_fixed_size_list_array(arr: &dyn Array) -> &FixedSizeListArray {
arr.as_any()
@@ -705,14 +729,22 @@ pub fn as_fixed_size_list_array(arr: &dyn Array) ->
&FixedSizeListArray {
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`LargeListArray`], panicking on failure.
+/// [`LargeListArray`].
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`LargeListArray`]
#[inline]
pub fn as_large_list_array(arr: &dyn Array) -> &LargeListArray {
as_generic_list_array::<i64>(arr)
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`GenericBinaryArray<S>`], panicking on failure.
+/// [`GenericBinaryArray<S>`].
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`GenericBinaryArray<S>`]
#[inline]
pub fn as_generic_binary_array<S: OffsetSizeTrait>(arr: &dyn Array) ->
&GenericBinaryArray<S> {
arr.as_any()
@@ -721,7 +753,7 @@ pub fn as_generic_binary_array<S: OffsetSizeTrait>(arr:
&dyn Array) -> &GenericB
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`StringArray`], panicking on failure.
+/// [`StringArray`].
///
/// # Example
///
@@ -733,6 +765,10 @@ pub fn as_generic_binary_array<S: OffsetSizeTrait>(arr:
&dyn Array) -> &GenericB
/// let arr: ArrayRef = Arc::new(StringArray::from_iter(vec![Some("foo")]));
/// let string_array = as_string_array(&arr);
/// ```
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`StringArray`]
pub fn as_string_array(arr: &dyn Array) -> &StringArray {
arr.as_any()
.downcast_ref::<StringArray>()
@@ -740,7 +776,7 @@ pub fn as_string_array(arr: &dyn Array) -> &StringArray {
}
/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`BooleanArray`], panicking on failure.
+/// [`BooleanArray`].
///
/// # Example
///
@@ -752,6 +788,10 @@ pub fn as_string_array(arr: &dyn Array) -> &StringArray {
/// let arr: ArrayRef = Arc::new(BooleanArray::from_iter(vec![Some(true)]));
/// let boolean_array = as_boolean_array(&arr);
/// ```
+///
+/// # Panics
+///
+/// Panics if `arr` is not a [`BooleanArray`]
pub fn as_boolean_array(arr: &dyn Array) -> &BooleanArray {
arr.as_any()
.downcast_ref::<BooleanArray>()
@@ -762,6 +802,11 @@ macro_rules! array_downcast_fn {
($name: ident, $arrty: ty, $arrty_str:expr) => {
#[doc = "Force downcast of an [`Array`], such as an [`ArrayRef`] to "]
#[doc = $arrty_str]
+ #[doc = ""]
+ #[doc = "# Panics"]
+ #[doc = ""]
+ #[doc = "Panics if `arr` is not a "]
+ #[doc = $arrty_str]
pub fn $name(arr: &dyn Array) -> &$arrty {
arr.as_any().downcast_ref::<$arrty>().expect(concat!(
"Unable to downcast to typed array through ",
@@ -772,11 +817,7 @@ macro_rules! array_downcast_fn {
// use recursive macro to generate dynamic doc string for a given array
type
($name: ident, $arrty: ty) => {
- array_downcast_fn!(
- $name,
- $arrty,
- concat!("[`", stringify!($arrty), "`], panicking on failure.")
- );
+ array_downcast_fn!($name, $arrty, concat!("[`", stringify!($arrty),
"`]"));
};
}
@@ -836,7 +877,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`BooleanArray`] returning `None` if not possible
fn as_boolean_opt(&self) -> Option<&BooleanArray>;
- /// Downcast this to a [`BooleanArray`] panicking if not possible
+ /// Downcast this to a [`BooleanArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`BooleanArray`]
fn as_boolean(&self) -> &BooleanArray {
self.as_boolean_opt().expect("boolean array")
}
@@ -844,7 +889,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`PrimitiveArray`] returning `None` if not possible
fn as_primitive_opt<T: ArrowPrimitiveType>(&self) ->
Option<&PrimitiveArray<T>>;
- /// Downcast this to a [`PrimitiveArray`] panicking if not possible
+ /// Downcast this to a [`PrimitiveArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`PrimitiveArray`]
fn as_primitive<T: ArrowPrimitiveType>(&self) -> &PrimitiveArray<T> {
self.as_primitive_opt().expect("primitive array")
}
@@ -852,7 +901,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`GenericByteArray`] returning `None` if not
possible
fn as_bytes_opt<T: ByteArrayType>(&self) -> Option<&GenericByteArray<T>>;
- /// Downcast this to a [`GenericByteArray`] panicking if not possible
+ /// Downcast this to a [`GenericByteArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`GenericByteArray`]
fn as_bytes<T: ByteArrayType>(&self) -> &GenericByteArray<T> {
self.as_bytes_opt().expect("byte array")
}
@@ -862,7 +915,11 @@ pub trait AsArray: private::Sealed {
self.as_bytes_opt()
}
- /// Downcast this to a [`GenericStringArray`] panicking if not possible
+ /// Downcast this to a [`GenericStringArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`GenericStringArray`]
fn as_string<O: OffsetSizeTrait>(&self) -> &GenericStringArray<O> {
self.as_bytes_opt().expect("string array")
}
@@ -872,7 +929,11 @@ pub trait AsArray: private::Sealed {
self.as_bytes_opt()
}
- /// Downcast this to a [`GenericBinaryArray`] panicking if not possible
+ /// Downcast this to a [`GenericBinaryArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`GenericBinaryArray`]
fn as_binary<O: OffsetSizeTrait>(&self) -> &GenericBinaryArray<O> {
self.as_bytes_opt().expect("binary array")
}
@@ -882,7 +943,11 @@ pub trait AsArray: private::Sealed {
self.as_byte_view_opt()
}
- /// Downcast this to a [`StringViewArray`] panicking if not possible
+ /// Downcast this to a [`StringViewArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`StringViewArray`]
fn as_string_view(&self) -> &StringViewArray {
self.as_byte_view_opt().expect("string view array")
}
@@ -892,7 +957,11 @@ pub trait AsArray: private::Sealed {
self.as_byte_view_opt()
}
- /// Downcast this to a [`BinaryViewArray`] panicking if not possible
+ /// Downcast this to a [`BinaryViewArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`BinaryViewArray`]
fn as_binary_view(&self) -> &BinaryViewArray {
self.as_byte_view_opt().expect("binary view array")
}
@@ -900,7 +969,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`GenericByteViewArray`] returning `None` if not
possible
fn as_byte_view_opt<T: ByteViewType>(&self) ->
Option<&GenericByteViewArray<T>>;
- /// Downcast this to a [`GenericByteViewArray`] panicking if not possible
+ /// Downcast this to a [`GenericByteViewArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`GenericByteViewArray`]
fn as_byte_view<T: ByteViewType>(&self) -> &GenericByteViewArray<T> {
self.as_byte_view_opt().expect("byte view array")
}
@@ -908,7 +981,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`StructArray`] returning `None` if not possible
fn as_struct_opt(&self) -> Option<&StructArray>;
- /// Downcast this to a [`StructArray`] panicking if not possible
+ /// Downcast this to a [`StructArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`StructArray`]
fn as_struct(&self) -> &StructArray {
self.as_struct_opt().expect("struct array")
}
@@ -916,7 +993,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`UnionArray`] returning `None` if not possible
fn as_union_opt(&self) -> Option<&UnionArray>;
- /// Downcast this to a [`UnionArray`] panicking if not possible
+ /// Downcast this to a [`UnionArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`UnionArray`]
fn as_union(&self) -> &UnionArray {
self.as_union_opt().expect("union array")
}
@@ -924,7 +1005,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`GenericListArray`] returning `None` if not
possible
fn as_list_opt<O: OffsetSizeTrait>(&self) -> Option<&GenericListArray<O>>;
- /// Downcast this to a [`GenericListArray`] panicking if not possible
+ /// Downcast this to a [`GenericListArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`GenericListArray`]
fn as_list<O: OffsetSizeTrait>(&self) -> &GenericListArray<O> {
self.as_list_opt().expect("list array")
}
@@ -932,7 +1017,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`GenericListViewArray`] returning `None` if not
possible
fn as_list_view_opt<O: OffsetSizeTrait>(&self) ->
Option<&GenericListViewArray<O>>;
- /// Downcast this to a [`GenericListViewArray`] panicking if not possible
+ /// Downcast this to a [`GenericListViewArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`GenericListViewArray`]
fn as_list_view<O: OffsetSizeTrait>(&self) -> &GenericListViewArray<O> {
self.as_list_view_opt().expect("list view array")
}
@@ -940,7 +1029,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`FixedSizeBinaryArray`] returning `None` if not
possible
fn as_fixed_size_binary_opt(&self) -> Option<&FixedSizeBinaryArray>;
- /// Downcast this to a [`FixedSizeBinaryArray`] panicking if not possible
+ /// Downcast this to a [`FixedSizeBinaryArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`FixedSizeBinaryArray`]
fn as_fixed_size_binary(&self) -> &FixedSizeBinaryArray {
self.as_fixed_size_binary_opt()
.expect("fixed size binary array")
@@ -949,7 +1042,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`FixedSizeListArray`] returning `None` if not
possible
fn as_fixed_size_list_opt(&self) -> Option<&FixedSizeListArray>;
- /// Downcast this to a [`FixedSizeListArray`] panicking if not possible
+ /// Downcast this to a [`FixedSizeListArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`FixedSizeListArray`]
fn as_fixed_size_list(&self) -> &FixedSizeListArray {
self.as_fixed_size_list_opt()
.expect("fixed size list array")
@@ -958,7 +1055,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`MapArray`] returning `None` if not possible
fn as_map_opt(&self) -> Option<&MapArray>;
- /// Downcast this to a [`MapArray`] panicking if not possible
+ /// Downcast this to a [`MapArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`MapArray`]
fn as_map(&self) -> &MapArray {
self.as_map_opt().expect("map array")
}
@@ -966,7 +1067,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`DictionaryArray`] returning `None` if not possible
fn as_dictionary_opt<K: ArrowDictionaryKeyType>(&self) ->
Option<&DictionaryArray<K>>;
- /// Downcast this to a [`DictionaryArray`] panicking if not possible
+ /// Downcast this to a [`DictionaryArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`DictionaryArray`]
fn as_dictionary<K: ArrowDictionaryKeyType>(&self) -> &DictionaryArray<K> {
self.as_dictionary_opt().expect("dictionary array")
}
@@ -974,7 +1079,11 @@ pub trait AsArray: private::Sealed {
/// Downcast this to a [`RunArray`] returning `None` if not possible
fn as_run_opt<K: RunEndIndexType>(&self) -> Option<&RunArray<K>>;
- /// Downcast this to a [`RunArray`] panicking if not possible
+ /// Downcast this to a [`RunArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`RunArray`]
fn as_run<K: RunEndIndexType>(&self) -> &RunArray<K> {
self.as_run_opt().expect("run array")
}
@@ -982,7 +1091,11 @@ pub trait AsArray: private::Sealed {
/// Downcasts this to a [`AnyDictionaryArray`] returning `None` if not
possible
fn as_any_dictionary_opt(&self) -> Option<&dyn AnyDictionaryArray>;
- /// Downcasts this to a [`AnyDictionaryArray`] panicking if not possible
+ /// Downcasts this to a [`AnyDictionaryArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`AnyDictionaryArray`]
fn as_any_dictionary(&self) -> &dyn AnyDictionaryArray {
self.as_any_dictionary_opt().expect("any dictionary array")
}
@@ -990,7 +1103,11 @@ pub trait AsArray: private::Sealed {
/// Downcasts this to a [`AnyRunEndArray`] returning `None` if not possible
fn as_any_ree_opt(&self) -> Option<&dyn AnyRunEndArray>;
- /// Downcasts this to a [`AnyRunEndArray`] panicking if not possible
+ /// Downcasts this to a [`AnyRunEndArray`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if this is not a [`AnyRunEndArray`]
fn as_any_ree(&self) -> &dyn AnyRunEndArray {
self.as_any_ree_opt().expect("any run end array")
}
diff --git a/arrow-array/src/ffi.rs b/arrow-array/src/ffi.rs
index 21e309a50d..8227034a9e 100644
--- a/arrow-array/src/ffi.rs
+++ b/arrow-array/src/ffi.rs
@@ -216,7 +216,7 @@ fn bit_width(data_type: &DataType, i: usize) ->
Result<usize> {
/// returns a new buffer corresponding to the index `i` of the FFI array. It
may not exist (null pointer).
/// `bits` is the number of bits that the native type of this buffer has.
/// The size of the buffer will be `ceil(self.length * bits, 8)`.
-/// # Panic
+/// # Panics
/// This function panics if `i` is larger or equal to `n_buffers`.
/// # Safety
/// This function assumes that `ceil(self.length * bits, 8)` is the size of
the buffer
diff --git a/arrow-array/src/types.rs b/arrow-array/src/types.rs
index 40cb3fd7fa..8988491314 100644
--- a/arrow-array/src/types.rs
+++ b/arrow-array/src/types.rs
@@ -945,6 +945,10 @@ impl Date32Type {
/// # Arguments
///
/// * `i` - The Date32Type to convert
+ ///
+ /// # Panics
+ ///
+ /// Panics on overflow
#[deprecated(since = "58.0.0", note = "Use to_naive_date_opt instead.")]
pub fn to_naive_date(i: <Date32Type as ArrowPrimitiveType>::Native) ->
NaiveDate {
Self::to_naive_date_opt(i)
@@ -979,6 +983,10 @@ impl Date32Type {
///
/// * `date` - The date on which to perform the operation
/// * `delta` - The interval to add
+ ///
+ /// # Panics
+ ///
+ /// Panics on overflow
#[deprecated(
since = "58.0.0",
note = "Use `add_year_months_opt` instead, which returns an Option to
handle overflow."
@@ -1016,6 +1024,10 @@ impl Date32Type {
///
/// * `date` - The date on which to perform the operation
/// * `delta` - The interval to add
+ ///
+ /// # Panics
+ ///
+ /// Panics on overflow
#[deprecated(
since = "58.0.0",
note = "Use `add_day_time_opt` instead, which returns an Option to
handle overflow."
@@ -1054,6 +1066,10 @@ impl Date32Type {
///
/// * `date` - The date on which to perform the operation
/// * `delta` - The interval to add
+ ///
+ /// # Panics
+ ///
+ /// Panics on overflow
#[deprecated(
since = "58.0.0",
note = "Use `add_month_day_nano_opt` instead, which returns an Option
to handle overflow."
@@ -1093,6 +1109,10 @@ impl Date32Type {
///
/// * `date` - The date on which to perform the operation
/// * `delta` - The interval to subtract
+ ///
+ /// # Panics
+ ///
+ /// Panics on overflow
#[deprecated(
since = "58.0.0",
note = "Use `subtract_year_months_opt` instead, which returns an
Option to handle overflow."
@@ -1130,6 +1150,10 @@ impl Date32Type {
///
/// * `date` - The date on which to perform the operation
/// * `delta` - The interval to subtract
+ ///
+ /// # Panics
+ ///
+ /// Panics on overflow
#[deprecated(
since = "58.0.0",
note = "Use `subtract_day_time_opt` instead, which returns an Option
to handle overflow."
@@ -1168,6 +1192,10 @@ impl Date32Type {
///
/// * `date` - The date on which to perform the operation
/// * `delta` - The interval to subtract
+ ///
+ /// # Panics
+ ///
+ /// Panics on overflow
#[deprecated(
since = "58.0.0",
note = "Use `subtract_month_day_nano_opt` instead, which returns an
Option to handle overflow."
diff --git a/arrow-buffer/src/bigint/mod.rs b/arrow-buffer/src/bigint/mod.rs
index 2f261deee0..c09a4480d6 100644
--- a/arrow-buffer/src/bigint/mod.rs
+++ b/arrow-buffer/src/bigint/mod.rs
@@ -518,6 +518,10 @@ impl i256 {
}
/// Performs wrapping division
+ ///
+ /// # Panics
+ ///
+ /// Panics if `other` is zero
#[inline]
pub fn wrapping_div(self, other: Self) -> Self {
match self.div_rem(other) {
@@ -534,6 +538,10 @@ impl i256 {
}
/// Performs wrapping remainder
+ ///
+ /// # Panics
+ ///
+ /// Panics if `other` is zero
#[inline]
pub fn wrapping_rem(self, other: Self) -> Self {
match self.div_rem(other) {
@@ -689,7 +697,10 @@ impl i256 {
}
/// Computes the `base` logarithm of the number `self`
- /// Panic if `self` is less than or equal to zero, or if `base` is less
than 2.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `self` is less than or equal to zero, or if `base` is less
than 2.
#[inline]
pub fn ilog(self, base: i256) -> u32 {
self.checked_ilog(base)
@@ -732,6 +743,9 @@ impl i256 {
}
/// Computes the decimal logarithm of the number `self`
+ ///
+ /// # Panics
+ ///
/// Panics if `self` is less than or equal to zero.
#[inline]
pub fn ilog10(self) -> u32 {
@@ -747,6 +761,10 @@ impl i256 {
}
/// Computes the base 2 logarithm of the number, rounded down.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `self` is less than or equal to zero
#[inline]
pub fn ilog2(self) -> u32 {
self.checked_ilog2()
diff --git a/arrow-buffer/src/buffer/boolean.rs
b/arrow-buffer/src/buffer/boolean.rs
index 591227a5c0..4943447c22 100644
--- a/arrow-buffer/src/buffer/boolean.rs
+++ b/arrow-buffer/src/buffer/boolean.rs
@@ -512,6 +512,10 @@ impl BooleanBuffer {
}
/// Slices this [`BooleanBuffer`] by the provided `offset` and `length`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `offset + len > self.len()`
pub fn slice(&self, offset: usize, len: usize) -> Self {
assert!(
offset.saturating_add(len) <= self.bit_len,
diff --git a/arrow-buffer/src/buffer/immutable.rs
b/arrow-buffer/src/buffer/immutable.rs
index 551bb1a921..2b3b698278 100644
--- a/arrow-buffer/src/buffer/immutable.rs
+++ b/arrow-buffer/src/buffer/immutable.rs
@@ -339,6 +339,10 @@ impl Buffer {
/// Returns a slice of this buffer starting at a certain bit offset.
/// If the offset is byte-aligned the returned buffer is a shallow clone,
/// otherwise a new buffer is allocated and filled with a copy of the bits
in the range.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `offset + len` is larger than the length of this buffer in
bits
pub fn bit_slice(&self, offset: usize, len: usize) -> Self {
if offset.is_multiple_of(8) {
return self.slice_with_length(offset / 8, bit_util::ceil(len, 8));
diff --git a/arrow-buffer/src/buffer/null.rs b/arrow-buffer/src/buffer/null.rs
index df8c73eea0..3303d8c350 100644
--- a/arrow-buffer/src/buffer/null.rs
+++ b/arrow-buffer/src/buffer/null.rs
@@ -118,6 +118,10 @@ impl NullBuffer {
/// Returns a new [`NullBuffer`] where each bit in the current null buffer
/// is repeated `count` times. This is useful for masking the nulls of
/// the child of a FixedSizeListArray based on its parent
+ ///
+ /// # Panics
+ ///
+ /// Panics if `self.len() * count` overflows `usize`
pub fn expand(&self, count: usize) -> Self {
let capacity = self.buffer.len().checked_mul(count).unwrap();
let mut buffer = MutableBuffer::new_null(capacity);
@@ -168,12 +172,20 @@ impl NullBuffer {
}
/// Returns `true` if the value at `idx` is not null
+ ///
+ /// # Panics
+ ///
+ /// Panics if `idx >= self.len()`
#[inline]
pub fn is_valid(&self, idx: usize) -> bool {
self.buffer.value(idx)
}
/// Returns `true` if the value at `idx` is null
+ ///
+ /// # Panics
+ ///
+ /// Panics if `idx >= self.len()`
#[inline]
pub fn is_null(&self, idx: usize) -> bool {
!self.is_valid(idx)
@@ -186,6 +198,10 @@ impl NullBuffer {
}
/// Slices this [`NullBuffer`] by the provided `offset` and `length`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `offset + len > self.len()`
pub fn slice(&self, offset: usize, len: usize) -> Self {
Self::new(self.buffer.slice(offset, len))
}
diff --git a/arrow-buffer/src/buffer/offset.rs
b/arrow-buffer/src/buffer/offset.rs
index 86ce100c23..f4c059a912 100644
--- a/arrow-buffer/src/buffer/offset.rs
+++ b/arrow-buffer/src/buffer/offset.rs
@@ -95,6 +95,10 @@ impl<O: ArrowNativeType> OffsetBuffer<O> {
}
/// Create a new [`OffsetBuffer`] containing `len + 1` `0` values
+ ///
+ /// # Panics
+ ///
+ /// Panics if `(len + 1) * size_of::<O>()` overflows `usize`
pub fn new_zeroed(len: usize) -> Self {
let len_bytes = len
.checked_add(1)
@@ -227,6 +231,10 @@ impl<O: ArrowNativeType> OffsetBuffer<O> {
}
/// Returns a zero-copy slice of this buffer with length `len` and
starting at `offset`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `offset + len > self.len()`
pub fn slice(&self, offset: usize, len: usize) -> Self {
Self(self.0.slice(offset, len.saturating_add(1)))
}
@@ -330,7 +338,9 @@ impl<O: ArrowNativeType> OffsetBuffer<O> {
/// Subtract `rhs` from all offsets
/// This will try to reuse the existing allocation as much as possible
///
- /// Panics: this will panic if `rhs` > the first offset or if `rhs` will
lead to overflow (when `rhs` is negative)
+ /// # Panics
+ ///
+ /// Panics if `rhs` > the first offset or if `rhs` will lead to overflow
(when `rhs` is negative)
///
/// # Example
///
diff --git a/arrow-buffer/src/buffer/scalar.rs
b/arrow-buffer/src/buffer/scalar.rs
index f74b93ab89..eeadfb13f7 100644
--- a/arrow-buffer/src/buffer/scalar.rs
+++ b/arrow-buffer/src/buffer/scalar.rs
@@ -112,6 +112,10 @@ impl<T: ArrowNativeType> ScalarBuffer<T> {
}
/// Returns a zero-copy slice of this buffer with length `len` and
starting at `offset`
+ ///
+ /// # Panics
+ ///
+ /// Panics for the same reasons as [`Self::new`]
pub fn slice(&self, offset: usize, len: usize) -> Self {
Self::new(self.buffer.clone(), offset, len)
}
diff --git a/arrow-buffer/src/builder/boolean.rs
b/arrow-buffer/src/builder/boolean.rs
index 4f84b0102b..d5871deca4 100644
--- a/arrow-buffer/src/builder/boolean.rs
+++ b/arrow-buffer/src/builder/boolean.rs
@@ -63,6 +63,10 @@ impl BooleanBufferBuilder {
}
/// Creates a new `BooleanBufferBuilder` from [`MutableBuffer`] of `len`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `len > buffer.len() * 8`
pub fn new_from_buffer(buffer: MutableBuffer, len: usize) -> Self {
assert!(len <= buffer.len() * 8);
let mut s = Self {
@@ -80,6 +84,10 @@ impl BooleanBufferBuilder {
}
/// Sets a bit in the buffer at `index`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `index / 8 >= self.as_slice().len()`
#[inline]
pub fn set_bit(&mut self, index: usize, v: bool) {
if v {
@@ -90,6 +98,10 @@ impl BooleanBufferBuilder {
}
/// Gets a bit in the buffer at `index`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `index / 8 >= self.as_slice().len()`
#[inline]
pub fn get_bit(&self, index: usize) -> bool {
bit_util::get_bit(self.buffer.as_slice(), index)
diff --git a/arrow-buffer/src/builder/null.rs b/arrow-buffer/src/builder/null.rs
index e98f25817a..5040208474 100644
--- a/arrow-buffer/src/builder/null.rs
+++ b/arrow-buffer/src/builder/null.rs
@@ -87,6 +87,10 @@ impl NullBufferBuilder {
}
/// Creates a new builder from a `MutableBuffer`.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `len > buffer.len() * 8`
pub fn new_from_buffer(buffer: MutableBuffer, len: usize) -> Self {
let capacity = buffer.len() * 8;
assert!(len <= capacity);
@@ -148,6 +152,10 @@ impl NullBufferBuilder {
}
/// Sets a bit in the builder at `index`
+ ///
+ /// # Panics
+ ///
+ /// Panics for the same reasons as [`BooleanBufferBuilder::set_bit`]
#[inline]
pub fn set_bit(&mut self, index: usize, v: bool) {
self.materialize_if_needed();
@@ -155,6 +163,11 @@ impl NullBufferBuilder {
}
/// Gets a bit in the buffer at `index`
+ ///
+ /// # Panics
+ ///
+ /// Panics for the same reasons as [`BooleanBufferBuilder::get_bit`], but
only if
+ /// a bitmap has been materialized (i.e. a null was appended)
#[inline]
pub fn is_valid(&self, index: usize) -> bool {
if let Some(ref buf) = self.bitmap_builder {
diff --git a/arrow-buffer/src/util/bit_iterator.rs
b/arrow-buffer/src/util/bit_iterator.rs
index 0760f89e4c..c2e65de0c8 100644
--- a/arrow-buffer/src/util/bit_iterator.rs
+++ b/arrow-buffer/src/util/bit_iterator.rs
@@ -34,7 +34,7 @@ impl<'a> BitIterator<'a> {
/// Create a new [`BitIterator`] from the provided `buffer`,
/// and `offset` and `len` in bits
///
- /// # Panic
+ /// # Panics
///
/// Panics if `buffer` is too short for the provided offset and length
pub fn new(buffer: &'a [u8], offset: usize, len: usize) -> Self {
diff --git a/arrow-buffer/src/util/bit_mask.rs
b/arrow-buffer/src/util/bit_mask.rs
index d248bd3c56..daec6c9a47 100644
--- a/arrow-buffer/src/util/bit_mask.rs
+++ b/arrow-buffer/src/util/bit_mask.rs
@@ -25,6 +25,11 @@ use crate::bit_util::ceil;
/// to be equal to the bits in `data` in the range
`[offset_read..offset_read+len]`
/// returns the number of `0` bits `data[offset_read..offset_read+len]`
/// `offset_write`, `offset_read`, and `len` are in terms of bits
+///
+/// # Panics
+///
+/// Panics if `offset_write + len` exceeds `write_data.len() * 8`, or if
+/// `offset_read + len` exceeds `data.len() * 8`
pub fn set_bits(
write_data: &mut [u8],
data: &[u8],
diff --git a/arrow-buffer/src/util/bit_util.rs
b/arrow-buffer/src/util/bit_util.rs
index 6fe4acb839..4ba42f761a 100644
--- a/arrow-buffer/src/util/bit_util.rs
+++ b/arrow-buffer/src/util/bit_util.rs
@@ -20,6 +20,10 @@
use crate::bit_chunk_iterator::BitChunks;
/// Returns the nearest number that is `>=` than `num` and is a multiple of 64
+///
+/// # Panics
+///
+/// Panics if rounding `num` up overflows `usize`
#[inline]
pub fn round_upto_multiple_of_64(num: usize) -> usize {
num.checked_next_multiple_of(64)
@@ -28,6 +32,10 @@ pub fn round_upto_multiple_of_64(num: usize) -> usize {
/// Returns the nearest multiple of `factor` that is `>=` than `num`. Here
`factor` must
/// be a power of 2.
+///
+/// # Panics
+///
+/// Panics if rounding `num` up overflows `usize`
pub fn round_upto_power_of_2(num: usize, factor: usize) -> usize {
debug_assert!(factor > 0 && factor.is_power_of_two());
num.checked_add(factor - 1)
@@ -36,6 +44,10 @@ pub fn round_upto_power_of_2(num: usize, factor: usize) ->
usize {
}
/// Returns whether bit at position `i` in `data` is set or not
+///
+/// # Panics
+///
+/// Panics if `i / 8 >= data.len()`
#[inline]
pub fn get_bit(data: &[u8], i: usize) -> bool {
data[i / 8] & (1 << (i % 8)) != 0
@@ -53,6 +65,10 @@ pub unsafe fn get_bit_raw(data: *const u8, i: usize) -> bool
{
}
/// Sets bit at position `i` for `data` to 1
+///
+/// # Panics
+///
+/// Panics if `i / 8 >= data.len()`
#[inline]
pub fn set_bit(data: &mut [u8], i: usize) {
data[i / 8] |= 1 << (i % 8);
@@ -72,6 +88,10 @@ pub unsafe fn set_bit_raw(data: *mut u8, i: usize) {
}
/// Sets bit at position `i` for `data` to 0
+///
+/// # Panics
+///
+/// Panics if `i / 8 >= data.len()`
#[inline]
pub fn unset_bit(data: &mut [u8], i: usize) {
data[i / 8] &= !(1 << (i % 8));
diff --git a/arrow-cast/src/base64.rs b/arrow-cast/src/base64.rs
index 1c1b53eb20..bd5474982a 100644
--- a/arrow-cast/src/base64.rs
+++ b/arrow-cast/src/base64.rs
@@ -29,6 +29,8 @@ pub use base64::prelude::*;
/// Base64 encode each element of `array` with the provided [`Engine`]
///
+/// # Panics
+///
/// Panics if the `Engine` emits output that is not valid UTF-8. A correct
/// `Engine` never does, but it is a safe trait so a misbehaving impl could;
/// validating keeps the returned [`GenericStringArray`] sound (#10284).
diff --git a/arrow-data/src/ffi.rs b/arrow-data/src/ffi.rs
index e82db398ba..e00b6eea49 100644
--- a/arrow-data/src/ffi.rs
+++ b/arrow-data/src/ffi.rs
@@ -298,7 +298,7 @@ impl FFI_ArrowArray {
/// Returns the buffer at the provided index
///
- /// # Panic
+ /// # Panics
/// Panics if index >= self.num_buffers() or the buffer is not correctly
aligned
#[inline]
pub fn buffer(&self, index: usize) -> *const u8 {
diff --git a/arrow-data/src/transform/mod.rs b/arrow-data/src/transform/mod.rs
index f57d8fcc9b..59b5948475 100644
--- a/arrow-data/src/transform/mod.rs
+++ b/arrow-data/src/transform/mod.rs
@@ -738,7 +738,7 @@ impl<'a> MutableArrayData<'a> {
/// # Errors
/// Returns an error if offset arithmetic overflows the underlying integer
type.
///
- /// # Panic
+ /// # Panics
/// This function panics if there is an invalid index,
/// i.e. `index` >= the number of source arrays
/// or `end` > the length of the `index`th array
@@ -762,7 +762,7 @@ impl<'a> MutableArrayData<'a> {
/// Extends the in progress array with a region of the input arrays.
///
- /// # Panic
+ /// # Panics
/// This function panics if there is an invalid index,
/// i.e. `index` >= the number of source arrays,
/// `end` > the length of the `index`th array,
diff --git a/arrow-ord/src/cmp.rs b/arrow-ord/src/cmp.rs
index 53ca258870..ad99b09e0e 100644
--- a/arrow-ord/src/cmp.rs
+++ b/arrow-ord/src/cmp.rs
@@ -860,6 +860,10 @@ impl<'a> ArrayOrd for &'a FixedSizeBinaryArray {
}
/// Compares two [`GenericByteViewArray`] at index `left_idx` and `right_idx`
+///
+/// # Panics
+///
+/// Panics if `left_idx >= left.len()` or `right_idx >= right.len()`
#[inline(always)]
pub fn compare_byte_view<T: ByteViewType>(
left: &GenericByteViewArray<T>,
diff --git a/arrow-row/src/lib.rs b/arrow-row/src/lib.rs
index 91e4f029af..c38a2849ee 100644
--- a/arrow-row/src/lib.rs
+++ b/arrow-row/src/lib.rs
@@ -1343,6 +1343,10 @@ pub type RowLengthIter<'a> = Map<Windows<'a, usize>,
fn(&'a [usize]) -> usize>;
impl Rows {
/// Append a [`Row`] to this [`Rows`]
+ ///
+ /// # Panics
+ ///
+ /// Panics if `row` was not produced by the same [`RowConverter`] as `self`
pub fn push(&mut self, row: Row<'_>) {
assert!(
Arc::ptr_eq(&row.config.fields, &self.config.fields),
@@ -1360,6 +1364,10 @@ impl Rows {
}
/// Returns the row at index `row`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `row >= self.num_rows()`
pub fn row(&self, row: usize) -> Row<'_> {
self.checked_row_end(row);
unsafe { self.row_unchecked(row) }
diff --git a/arrow-schema/src/ffi.rs b/arrow-schema/src/ffi.rs
index 3788e80338..6bff0c85df 100644
--- a/arrow-schema/src/ffi.rs
+++ b/arrow-schema/src/ffi.rs
@@ -131,6 +131,10 @@ unsafe extern "C" fn release_schema(schema: *mut
FFI_ArrowSchema) {
impl FFI_ArrowSchema {
/// create a new [`FFI_ArrowSchema`]. This fails if the fields'
/// [`DataType`] is not supported.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `format` contains an interior nul byte
pub fn try_new(
format: &str,
children: Vec<FFI_ArrowSchema>,
@@ -276,6 +280,10 @@ impl FFI_ArrowSchema {
}
/// Returns the format of this schema.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the format field is null or is not valid UTF-8
pub fn format(&self) -> &str {
assert!(!self.format.is_null());
// safe because the lifetime of `self.format` equals `self`
@@ -285,6 +293,10 @@ impl FFI_ArrowSchema {
}
/// Returns the name of this schema.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the name field is not valid UTF-8
pub fn name(&self) -> Option<&str> {
if self.name.is_null() {
None
diff --git a/arrow-schema/src/field.rs b/arrow-schema/src/field.rs
index f360b46c08..a95ecf1ee4 100644
--- a/arrow-schema/src/field.rs
+++ b/arrow-schema/src/field.rs
@@ -554,7 +554,7 @@ impl Field {
/// Returns an instance of the given [`ExtensionType`] of this [`Field`],
/// panics if this [`Field`] does not have this extension type.
///
- /// # Panic
+ /// # Panics
///
/// This calls [`Field::try_extension_type`] and panics when it returns an
/// error.
diff --git a/arrow/src/util/bench_util.rs b/arrow/src/util/bench_util.rs
index 2ec9d0de76..ec757b1a07 100644
--- a/arrow/src/util/bench_util.rs
+++ b/arrow/src/util/bench_util.rs
@@ -245,6 +245,10 @@ fn create_string_array_with_len_range_and_prefix<Offset:
OffsetSizeTrait>(
/// Creates a random [`GenericStringArray`] of a given `size` and
`null_density`
/// filling it with random strings with lengths in the specified range,
/// all starting with the provided `prefix`, generated using the provided
`seed`.
+///
+/// # Panics
+///
+/// Panics if `min_str_len > max_str_len` or `prefix.len() > max_str_len`
pub fn create_string_array_with_len_range_and_prefix_and_seed<Offset:
OffsetSizeTrait>(
size: usize,
null_density: f32,
@@ -619,6 +623,10 @@ where
}
/// Create primitive run array for given logical and physical array lengths
+///
+/// # Panics
+///
+/// Panics if `logical_array_len < physical_array_len`
pub fn create_primitive_run_array<R: RunEndIndexType, V: ArrowPrimitiveType>(
logical_array_len: usize,
physical_array_len: usize,
@@ -653,6 +661,10 @@ pub fn create_primitive_run_array<R: RunEndIndexType, V:
ArrowPrimitiveType>(
/// Create string array to be used by run array builder. The string array
/// will result in run array with physical length of `physical_array_len`
/// and logical length of `logical_array_len`
+///
+/// # Panics
+///
+/// Panics if `logical_array_len < physical_array_len`
pub fn create_string_array_for_runs(
physical_array_len: usize,
logical_array_len: usize,
@@ -733,6 +745,10 @@ pub fn create_binary_array_with_seed<Offset:
OffsetSizeTrait>(
/// filling it with random bytes with lengths in the specified range,
/// all starting with the provided `prefix`, generated using the provided
`seed`.
///
+///
+/// # Panics
+///
+/// Panics if `min_len > max_len` or `prefix.len() > max_len`
pub fn create_binary_array_with_len_range_and_prefix_and_seed<Offset:
OffsetSizeTrait>(
size: usize,
null_density: f32,
@@ -978,6 +994,10 @@ where
///
/// Useful for building arrays and record batches in benchmarks without
/// repeating per-type construction logic. Panics on unsupported types.
+///
+/// # Panics
+///
+/// Panics if `data_type` is not supported
pub fn create_array_for_type(data_type: &DataType, size: usize, null_density:
f32) -> ArrayRef {
match data_type {
DataType::Boolean => Arc::new(create_boolean_array(size, null_density,
0.5)),
diff --git a/arrow/src/util/test_util.rs b/arrow/src/util/test_util.rs
index 7748e95ce4..2a8bf05852 100644
--- a/arrow/src/util/test_util.rs
+++ b/arrow/src/util/test_util.rs
@@ -64,14 +64,16 @@ pub fn get_temp_file(file_name: &str, content: &[u8]) ->
fs::File {
/// The default can be overridden by the optional environment
/// variable `ARROW_TEST_DATA`
///
-/// panics when the directory can not be found.
-///
/// Example:
/// ```
/// let testdata = arrow::util::test_util::arrow_test_data();
/// let csvdata = format!("{}/csv/aggregate_test_100.csv", testdata);
/// assert!(std::path::PathBuf::from(csvdata).exists());
/// ```
+///
+/// # Panics
+///
+/// Panics if the directory can not be found
pub fn arrow_test_data() -> String {
match get_data_dir("ARROW_TEST_DATA", "../testing/data") {
Ok(pb) => pb.display().to_string(),
@@ -86,14 +88,16 @@ pub fn arrow_test_data() -> String {
/// The default can be overridden by the optional environment variable
/// `PARQUET_TEST_DATA`
///
-/// panics when the directory can not be found.
-///
/// Example:
/// ```
/// let testdata = arrow::util::test_util::parquet_test_data();
/// let filename = format!("{}/binary.parquet", testdata);
/// assert!(std::path::PathBuf::from(filename).exists());
/// ```
+///
+/// # Panics
+///
+/// Panics if the directory can not be found
pub fn parquet_test_data() -> String {
match get_data_dir("PARQUET_TEST_DATA", "../parquet-testing/data") {
Ok(pb) => pb.display().to_string(),
@@ -166,6 +170,10 @@ pub struct BadIterator<T> {
impl<T> BadIterator<T> {
/// Create a new iterator for `<limit>` items, but that reports to
/// produce `<claimed>` items. Must provide at least 1 item.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `items` is empty
pub fn new(limit: usize, claimed: usize, items: Vec<T>) -> Self {
assert!(!items.is_empty());
Self {
diff --git a/parquet-variant/src/builder/object.rs
b/parquet-variant/src/builder/object.rs
index 41d5e40c9d..62c9e40704 100644
--- a/parquet-variant/src/builder/object.rs
+++ b/parquet-variant/src/builder/object.rs
@@ -211,9 +211,11 @@ impl<'a, S: BuilderSpecificState> ObjectBuilder<'a, S> {
/// Returns an object builder that can be used to append a new (nested)
object to this object.
///
- /// Panics if the proposed key was a duplicate
- ///
/// WARNING: The builder will have no effect unless/until
[`ObjectBuilder::finish`] is called.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the proposed key was a duplicate
pub fn new_object<'b>(&'b mut self, key: &'b str) -> ObjectBuilder<'b,
ObjectState<'b>> {
self.try_new_object(key).unwrap()
}
@@ -233,9 +235,11 @@ impl<'a, S: BuilderSpecificState> ObjectBuilder<'a, S> {
/// Returns a list builder that can be used to append a new (nested) list
to this object.
///
- /// Panics if the proposed key was a duplicate
- ///
/// WARNING: The builder will have no effect unless/until
[`ListBuilder::finish`] is called.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the proposed key was a duplicate
pub fn new_list<'b>(&'b mut self, key: &str) -> ListBuilder<'b,
ObjectState<'b>> {
self.try_new_list(key).unwrap()
}
diff --git a/parquet-variant/src/variant.rs b/parquet-variant/src/variant.rs
index a61cfbaca2..1a1990d743 100644
--- a/parquet-variant/src/variant.rs
+++ b/parquet-variant/src/variant.rs
@@ -318,6 +318,11 @@ impl<'m, 'v> Variant<'m, 'v> {
/// ```
///
/// [unvalidated]: Self#Validation
+ ///
+ /// # Panics
+ ///
+ /// Panics if `metadata` or `value` fail basic validation. Use
[`Self::try_new`]
+ /// for a fallible version.
pub fn new(metadata: &'m [u8], value: &'v [u8]) -> Self {
let metadata =
VariantMetadata::try_new_with_shallow_validation(metadata)
.expect("Invalid variant metadata");
@@ -353,6 +358,11 @@ impl<'m, 'v> Variant<'m, 'v> {
/// Similar to [`Self::try_new_with_metadata`], but [unvalidated].
///
/// [unvalidated]: Self#Validation
+ ///
+ /// # Panics
+ ///
+ /// Panics if `value` fails basic validation. Use
[`Self::try_new_with_metadata`]
+ /// for a fallible version.
pub fn new_with_metadata(metadata: VariantMetadata<'m>, value: &'v [u8])
-> Self {
Self::try_new_with_metadata_and_shallow_validation(metadata, value)
.expect("Invalid variant")
diff --git a/parquet-variant/src/variant/list.rs
b/parquet-variant/src/variant/list.rs
index 7301d05706..9d9f4cdec4 100644
--- a/parquet-variant/src/variant/list.rs
+++ b/parquet-variant/src/variant/list.rs
@@ -145,6 +145,14 @@ impl<'m, 'v> VariantList<'m, 'v> {
Self::try_new_with_shallow_validation(metadata,
value)?.with_full_validation()
}
+ /// Interprets `metadata` and `value` as a variant list, performing only
basic
+ /// (constant-cost) [validation].
+ ///
+ /// # Panics
+ ///
+ /// Panics if basic validation fails. Use [`Self::try_new`] for a fallible
version.
+ ///
+ /// [validation]: Self#Validation
pub fn new(metadata: VariantMetadata<'m>, value: &'v [u8]) -> Self {
Self::try_new_with_shallow_validation(metadata, value).expect("Invalid
variant list value")
}
@@ -250,7 +258,11 @@ impl<'m, 'v> VariantList<'m, 'v> {
self.len() == 0
}
- /// Returns element by index in `0..self.len()`, if any. May panic if this
list is [invalid].
+ /// Returns element by index in `0..self.len()`, if any.
+ ///
+ /// # Panics
+ ///
+ /// Panics if this list is [invalid]. Use [`Self::try_get`] for a fallible
version.
///
/// [invalid]: Self#Validation
pub fn get(&self, index: usize) -> Option<Variant<'m, 'v>> {
@@ -280,6 +292,11 @@ impl<'m, 'v> VariantList<'m, 'v> {
/// [`Self::iter_try`] to avoid panics due to invalid data.
///
/// [unvalidated]: Self#Validation
+ ///
+ /// # Panics
+ ///
+ /// Panics if the underlying bytes are invalid. Use [`Self::iter_try`] for
a
+ /// fallible version.
pub fn iter(&self) -> impl Iterator<Item = Variant<'m, 'v>> + '_ {
self.iter_try_with_shallow_validation()
.map(|result| result.expect("Invalid variant list entry"))
diff --git a/parquet-variant/src/variant/metadata.rs
b/parquet-variant/src/variant/metadata.rs
index a1226a8197..b48c50451b 100644
--- a/parquet-variant/src/variant/metadata.rs
+++ b/parquet-variant/src/variant/metadata.rs
@@ -198,6 +198,10 @@ impl<'m> VariantMetadata<'m> {
/// needed, instead of paying expensive full validation up front).
///
/// [validate]: Self#Validation
+ ///
+ /// # Panics
+ ///
+ /// Panics if basic sanity checking fails. Use [`Self::try_new`] for a
fallible version.
pub fn new(bytes: &'m [u8]) -> Self {
Self::try_new_with_shallow_validation(bytes).expect("Invalid variant
metadata")
}
@@ -375,7 +379,9 @@ impl<'m> VariantMetadata<'m> {
/// name is not present. The search cost is logarithmic if
[`Self::is_sorted`] and linear
/// otherwise.
///
- /// WARNING: This method panics if the underlying bytes are [invalid].
+ /// # Panics
+ ///
+ /// Panics if the underlying bytes are [invalid].
///
/// [invalid]: Self#Validation
pub fn get_entry(&self, field_name: &str) -> Option<(u32, &'m str)> {
@@ -402,6 +408,11 @@ impl<'m> VariantMetadata<'m> {
/// [`Self::iter_try`] to avoid panics due to invalid data.
///
/// [unvalidated]: Self#Validation
+ ///
+ /// # Panics
+ ///
+ /// Panics if the underlying bytes are invalid. Use [`Self::iter_try`] for
a
+ /// fallible version.
pub fn iter(&self) -> impl Iterator<Item = &'m str> + '_ {
self.iter_try()
.map(|result| result.expect("Invalid metadata dictionary entry"))
diff --git a/parquet-variant/src/variant/object.rs
b/parquet-variant/src/variant/object.rs
index cf563d9e35..d871cac61b 100644
--- a/parquet-variant/src/variant/object.rs
+++ b/parquet-variant/src/variant/object.rs
@@ -134,6 +134,14 @@ const _: () =
crate::utils::expect_size_of::<VariantObject>(64);
const _: () = crate::utils::expect_size_of::<VariantObject>(44);
impl<'m, 'v> VariantObject<'m, 'v> {
+ /// Interprets `metadata` and `value` as a variant object, performing only
basic
+ /// (constant-cost) [validation].
+ ///
+ /// # Panics
+ ///
+ /// Panics if basic validation fails. Use [`Self::try_new`] for a fallible
version.
+ ///
+ /// [validation]: Self#Validation
pub fn new(metadata: VariantMetadata<'m>, value: &'v [u8]) -> Self {
Self::try_new_with_shallow_validation(metadata, value).expect("Invalid
variant object")
}
@@ -366,6 +374,10 @@ impl<'m, 'v> VariantObject<'m, 'v> {
}
/// Returns an iterator of (name, value) pairs over the fields of this
object.
+ ///
+ /// # Panics
+ ///
+ /// Panics if this object is invalid. Use [`Self::iter_try`] for a
fallible version.
pub fn iter(&self) -> impl Iterator<Item = (&'m str, Variant<'m, 'v>)> +
'_ {
self.iter_try_with_shallow_validation()
.map(|result| result.expect("Invalid variant object field value"))
diff --git a/parquet/src/arrow/arrow_reader/selection/mod.rs
b/parquet/src/arrow/arrow_reader/selection/mod.rs
index 517022f173..c01da6b905 100644
--- a/parquet/src/arrow/arrow_reader/selection/mod.rs
+++ b/parquet/src/arrow/arrow_reader/selection/mod.rs
@@ -305,7 +305,7 @@ impl RowSelection {
/// Creates a [`RowSelection`] from a slice of [`BooleanArray`]
///
- /// # Panic
+ /// # Panics
///
/// Panics if any of the [`BooleanArray`] contain nulls
pub fn from_filters(filters: &[BooleanArray]) -> Self {
diff --git a/parquet/src/arrow/buffer/dictionary_buffer.rs
b/parquet/src/arrow/buffer/dictionary_buffer.rs
index 33537b40f8..1450bc16b0 100644
--- a/parquet/src/arrow/buffer/dictionary_buffer.rs
+++ b/parquet/src/arrow/buffer/dictionary_buffer.rs
@@ -51,7 +51,7 @@ impl<K: ArrowNativeType + Ord, V: OffsetSizeTrait>
DictionaryBuffer<K, V> {
///
/// Returns None if the dictionary needs to be recomputed
///
- /// # Panic
+ /// # Panics
///
/// Panics if the dictionary is too large for `K`
pub fn as_keys(&mut self, dictionary: &ArrayRef) -> Option<&mut Vec<K>> {
diff --git a/parquet/src/column/reader.rs b/parquet/src/column/reader.rs
index 0bf5dd822d..61c8c766ed 100644
--- a/parquet/src/column/reader.rs
+++ b/parquet/src/column/reader.rs
@@ -89,6 +89,8 @@ pub fn get_column_reader(
/// Gets a typed column reader for the specific type `T`, by "up-casting"
`col_reader` of
/// non-generic type to a generic column reader type `ColumnReaderImpl`.
///
+/// # Panics
+///
/// Panics if actual enum value for `col_reader` does not match the type `T`.
pub fn get_typed_column_reader<T: DataType>(col_reader: ColumnReader) ->
ColumnReaderImpl<T> {
T::get_column_reader(col_reader).unwrap_or_else(|| {
diff --git a/parquet/src/column/writer/mod.rs b/parquet/src/column/writer/mod.rs
index 52daecf75f..5aa3c40482 100644
--- a/parquet/src/column/writer/mod.rs
+++ b/parquet/src/column/writer/mod.rs
@@ -157,6 +157,8 @@ pub fn get_column_writer<'a>(
/// Gets a typed column writer for the specific type `T`, by "up-casting"
`col_writer` of
/// non-generic type to a generic column writer type `ColumnWriterImpl`.
///
+/// # Panics
+///
/// Panics if actual enum value for `col_writer` does not match the type `T`.
pub fn get_typed_column_writer<T: DataType>(col_writer: ColumnWriter) ->
ColumnWriterImpl<T> {
T::get_column_writer(col_writer).unwrap_or_else(|| {
diff --git a/parquet/src/data_type.rs b/parquet/src/data_type.rs
index 1558d9cb80..8895280110 100644
--- a/parquet/src/data_type.rs
+++ b/parquet/src/data_type.rs
@@ -217,6 +217,10 @@ impl ByteArray {
}
/// Gets length of the underlying byte buffer.
+ ///
+ /// # Panics
+ ///
+ /// Panics if no data has been set, e.g. on a [`ByteArray::new`] instance
#[inline]
pub fn len(&self) -> usize {
assert!(self.data.is_some());
@@ -224,12 +228,20 @@ impl ByteArray {
}
/// Checks if the underlying buffer is empty.
+ ///
+ /// # Panics
+ ///
+ /// Panics if no data has been set, see [`Self::len`]
#[inline]
pub fn is_empty(&self) -> bool {
self.len() == 0
}
/// Returns slice of data.
+ ///
+ /// # Panics
+ ///
+ /// Panics if no data has been set
#[inline]
pub fn data(&self) -> &[u8] {
self.data
@@ -245,6 +257,10 @@ impl ByteArray {
}
/// Returns `ByteArray` instance with slice of values for a data.
+ ///
+ /// # Panics
+ ///
+ /// Panics if no data has been set, or if `start + len` is out of bounds
#[inline]
pub fn slice(&self, start: usize, len: usize) -> Self {
Self::from(
diff --git a/parquet/src/file/metadata/mod.rs b/parquet/src/file/metadata/mod.rs
index 874449d992..8c8be1994e 100644
--- a/parquet/src/file/metadata/mod.rs
+++ b/parquet/src/file/metadata/mod.rs
@@ -1054,6 +1054,10 @@ impl ColumnChunkMetaData {
}
/// Returns the offset and length in bytes of the column chunk within the
file
+ ///
+ /// # Panics
+ ///
+ /// Panics if the column start offset or the compressed size is negative
pub fn byte_range(&self) -> (u64, u64) {
let col_start = match self.dictionary_page_offset() {
Some(dictionary_page_offset) => dictionary_page_offset,
diff --git a/parquet/src/file/properties.rs b/parquet/src/file/properties.rs
index 78b1ee9950..074f26fef8 100644
--- a/parquet/src/file/properties.rs
+++ b/parquet/src/file/properties.rs
@@ -823,6 +823,10 @@ impl WriterPropertiesBuilder {
/// * If `None`, there's no effective limit.
///
/// [`Index`]: crate::file::page_index::column_index::ColumnIndexMetaData
+ ///
+ /// # Panics
+ ///
+ /// Panics if `max_length` is `Some(0)`
pub fn set_column_index_truncate_length(mut self, max_length:
Option<usize>) -> Self {
if let Some(value) = max_length {
assert!(
@@ -852,6 +856,10 @@ impl WriterPropertiesBuilder {
/// [`WriterPropertiesBuilder::set_column_index_truncate_length`]
///
/// [`Statistics`]: crate::file::statistics::Statistics
+ ///
+ /// # Panics
+ ///
+ /// Panics if `max_length` is `Some(0)`
pub fn set_statistics_truncate_length(mut self, max_length: Option<usize>)
-> Self {
if let Some(value) = max_length {
assert!(
@@ -1536,6 +1544,9 @@ impl BloomFilterPropertiesBuilder {
/// Builds [`BloomFilterProperties`].
///
+ ///
+ /// # Panics
+ ///
/// Panics if the configured `fpp` is not in `(0.0, 1.0)` exclusive.
/// Use [`Self::try_build`] for a non-panicking alternative.
pub fn build(self) -> BloomFilterProperties {
diff --git a/parquet/src/file/serialized_reader.rs
b/parquet/src/file/serialized_reader.rs
index fe9a5c0486..e0a8d079e7 100644
--- a/parquet/src/file/serialized_reader.rs
+++ b/parquet/src/file/serialized_reader.rs
@@ -128,6 +128,10 @@ impl ReadOptionsBuilder {
/// Add a range predicate on filtering row groups if their midpoints are
within
/// the Closed-Open range `[start..end) {x | start <= x < end}`
+ ///
+ /// # Panics
+ ///
+ /// Panics if `end <= start`
pub fn with_range(mut self, start: i64, end: i64) -> Self {
assert!(start < end);
let predicate = move |rg: &RowGroupMetaData, _: usize| {
diff --git a/parquet/src/schema/types.rs b/parquet/src/schema/types.rs
index c7e66231fa..186c2744e5 100644
--- a/parquet/src/schema/types.rs
+++ b/parquet/src/schema/types.rs
@@ -106,7 +106,10 @@ impl Type {
}
/// Gets the fields from this group type.
- /// Note that this will panic if called on a non-group type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-group type
// TODO: should we return `&[&Type]` here?
pub fn get_fields(&self) -> &[TypePtr] {
match *self {
@@ -116,7 +119,10 @@ impl Type {
}
/// Gets physical type of this primitive type.
- /// Note that this will panic if called on a non-primitive type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-primitive type
pub fn get_physical_type(&self) -> PhysicalType {
match *self {
Type::PrimitiveType {
@@ -129,7 +135,10 @@ impl Type {
}
/// Gets precision of this primitive type.
- /// Note that this will panic if called on a non-primitive type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-primitive type
pub fn get_precision(&self) -> i32 {
match *self {
Type::PrimitiveType { precision, .. } => precision,
@@ -138,7 +147,10 @@ impl Type {
}
/// Gets scale of this primitive type.
- /// Note that this will panic if called on a non-primitive type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-primitive type
pub fn get_scale(&self) -> i32 {
match *self {
Type::PrimitiveType { scale, .. } => scale,
@@ -704,6 +716,10 @@ impl BasicTypeInfo {
}
/// Returns [`Repetition`] value for the type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the repetition is not set, see [`Self::has_repetition`]
pub fn repetition(&self) -> Repetition {
assert!(self.repetition.is_some());
self.repetition.unwrap()
@@ -725,6 +741,10 @@ impl BasicTypeInfo {
}
/// Returns id value for the type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the id is not set, see [`Self::has_id`]
pub fn id(&self) -> i32 {
assert!(self.id.is_some());
self.id.unwrap()
@@ -950,7 +970,10 @@ impl ColumnDescriptor {
}
/// Returns physical type for this column.
- /// Note that it will panic if called on a non-primitive type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-primitive type
pub fn physical_type(&self) -> PhysicalType {
match self.primitive_type.as_ref() {
Type::PrimitiveType { physical_type, .. } => *physical_type,
@@ -959,7 +982,10 @@ impl ColumnDescriptor {
}
/// Returns type length for this column.
- /// Note that it will panic if called on a non-primitive type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-primitive type
pub fn type_length(&self) -> i32 {
match self.primitive_type.as_ref() {
Type::PrimitiveType { type_length, .. } => *type_length,
@@ -968,7 +994,10 @@ impl ColumnDescriptor {
}
/// Returns type precision for this column.
- /// Note that it will panic if called on a non-primitive type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-primitive type
pub fn type_precision(&self) -> i32 {
match self.primitive_type.as_ref() {
Type::PrimitiveType { precision, .. } => *precision,
@@ -977,7 +1006,10 @@ impl ColumnDescriptor {
}
/// Returns type scale for this column.
- /// Note that it will panic if called on a non-primitive type.
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a non-primitive type
pub fn type_scale(&self) -> i32 {
match self.primitive_type.as_ref() {
Type::PrimitiveType { scale, .. } => *scale,
@@ -1098,6 +1130,10 @@ impl SchemaDescriptor {
}
/// Returns [`ColumnDescriptor`] for a field position.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `i >= self.num_columns()`
pub fn column(&self, i: usize) -> ColumnDescPtr {
assert!(
i < self.leaves.len(),
@@ -1125,12 +1161,20 @@ impl SchemaDescriptor {
}
/// Returns column root [`Type`] pointer for a leaf position.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `i >= self.num_columns()`
pub fn get_column_root_ptr(&self, i: usize) -> TypePtr {
let result = self.column_root_of(i);
result.clone()
}
/// Returns the index of the root column for a field position
+ ///
+ /// # Panics
+ ///
+ /// Panics if `leaf` is out of bounds
pub fn get_column_root_idx(&self, leaf: usize) -> usize {
assert!(
leaf < self.leaves.len(),
