scovich commented on code in PR #12309:
URL: https://github.com/apache/arrow-rs/pull/12309#discussion_r4645980276


##########
parquet-variant/src/variant/view.rs:
##########
@@ -0,0 +1,771 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for 
additional information regarding copyright ownership
+// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) 
under one or more contributor license agreements
+
+//! Views over encoded variant bytes that read only what they use. See 
[`VariantView`].
+
+use arrow_schema::ArrowError;
+
+use crate::decoder::{VariantBasicType, get_basic_type};
+use crate::utils::{
+    first_byte_from_slice, overflow_error, slice_from_slice, 
slice_from_slice_at_offset,
+    str_from_bytes, try_binary_search,
+};
+use crate::variant::list::VariantListHeader;
+use crate::variant::metadata::VariantMetadataHeader;
+use crate::variant::object::VariantObjectHeader;
+use crate::variant::{
+    EMPTY_VARIANT_METADATA, Variant, VariantList, VariantMetadata, 
VariantObject,
+};
+
+/// The size of the header byte of a metadata dictionary, object or list.
+const NUM_HEADER_BYTES: u32 = 1;
+
+#[inline]
+fn checked(value: Option<u32>, what: &str) -> Result<u32, ArrowError> {
+    value.ok_or_else(|| overflow_error(what))
+}
+
+fn index_error(kind: &str, index: usize, len: usize) -> ArrowError {
+    ArrowError::InvalidArgumentError(format!(
+        "{kind} index {index} is out of bounds for length {len}"
+    ))
+}
+
+/// A metadata dictionary of which only the header has been read. See 
[`VariantView`].
+#[derive(Debug, Clone, Copy)]
+pub struct VariantMetadataView<'m> {
+    pub(crate) bytes: &'m [u8],
+    pub(crate) header: VariantMetadataHeader,
+    pub(crate) dictionary_size: u32,
+    pub(crate) first_value_byte: u32,
+}
+
+impl<'m> VariantMetadataView<'m> {
+    /// Reads the header and the dictionary size of the metadata dictionary in 
`bytes`.
+    #[inline]
+    pub fn try_new(bytes: &'m [u8]) -> Result<Self, ArrowError> {
+        let header = 
VariantMetadataHeader::try_new(first_byte_from_slice(bytes)?)?;
+        let dictionary_size =
+            header
+                .offset_size
+                .unpack_u32_at_offset(bytes, NUM_HEADER_BYTES as _, 0)?;
+
+        // There are dictionary_size + 1 offsets, and the string bytes 
immediately follow them.
+        let first_value_byte = checked(
+            dictionary_size
+                .checked_add(1)
+                .and_then(|n| n.checked_mul(header.offset_size()))
+                .and_then(|n| n.checked_add(header.first_offset_byte())),
+            "offset of variant metadata dictionary",
+        )?;
+
+        Ok(Self {
+            bytes,
+            header,
+            dictionary_size,
+            first_value_byte,
+        })
+    }
+
+    /// The number of entries in the dictionary.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.dictionary_size as _
+    }
+
+    /// True if the dictionary has no entries.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dictionary_size == 0
+    }
+
+    /// True if the header declares the entries unique and sorted.
+    #[inline]
+    pub fn is_sorted(&self) -> bool {
+        self.header.is_sorted
+    }
+
+    /// The bytes of entry `id`, without UTF-8 validation.
+    #[inline]
+    pub fn entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        if id >= self.len() {
+            return Err(index_error("Metadata dictionary", id, self.len()));
+        }
+        self.read_entry(id)
+    }
+
+    /// The entry `id` as a string.
+    pub fn entry_str(&self, id: usize) -> Result<&'m str, ArrowError> {
+        str_from_bytes(self.entry(id)?)
+    }
+
+    /// The id of the entry equal to `name`, if any.
+    ///
+    /// The search is a binary search if the dictionary is sorted and has more 
than a few entries,
+    /// and a linear scan otherwise.
+    pub fn find(&self, name: &[u8]) -> Result<Option<u32>, ArrowError> {
+        if self.is_sorted() && self.len() > 10 {
+            let found = try_binary_search(self.len(), |id| 
Ok(self.read_entry(id)?.cmp(name)))?;
+            return Ok(found.map(|id| id as u32));
+        }
+        for id in 0..self.len() {
+            if self.read_entry(id)? == name {
+                return Ok(Some(id as u32));
+            }
+        }
+        Ok(None)
+    }
+
+    /// Checks the first and last offsets, and returns the bounded 
[`VariantMetadata`].
+    #[inline]
+    pub fn into_metadata(self) -> Result<VariantMetadata<'m>, ArrowError> {
+        VariantMetadata::try_from_view(self)
+    }
+
+    /// Entry `i` of the offset array, for `i` in `0..=self.len()`.
+    #[inline]
+    pub(crate) fn offset(&self, i: usize) -> Result<u32, ArrowError> {
+        self.header.offset_size.unpack_u32_at_offset(
+            self.bytes,
+            self.header.first_offset_byte() as _,
+            i,
+        )
+    }
+
+    // The bytes of entry `id`, for `id` in `0..self.len()`.
+    #[inline]
+    fn read_entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        let range = self.offset(id)? as usize..self.offset(id + 1)? as usize;
+        slice_from_slice_at_offset(self.bytes, self.first_value_byte as _, 
range)
+    }
+}
+
+/// A variant value of which only the header byte has been read.
+///
+/// Building a view parses one header and nothing else. Each accessor reads 
and bounds-checks only
+/// the bytes it needs, so malformed input produces an error, never a panic. A 
view does not check
+/// UTF-8, sort order, or any offset it does not read. Field names are 
compared as bytes, which
+/// orders them exactly as `str` does.
+///
+/// Use a view to read a few values out of a variant, such as one path per row 
of a column, without
+/// paying for checks that the access does not use.
+///
+/// # Views and validation
+///
+/// The views [`VariantView`], [`VariantMetadataView`], [`VariantObjectView`] 
and
+/// [`VariantListView`] are the weakest state of a variant. The [`Variant`], 
[`VariantMetadata`],
+/// [`VariantObject`] and [`VariantList`] types are the stronger states:
+///
+/// - [`VariantView::to_variant`], [`VariantMetadataView::into_metadata`],
+///   [`VariantObjectView::into_object`] and [`VariantListView::into_list`] 
check the first and
+///   last offsets, which bound the encoding. Unvalidated instances of the 
stronger types guarantee
+///   those checks.
+/// - The `with_full_validation` methods of the stronger types check 
everything else.
+///
+/// # Example
+///
+/// ```
+/// # use parquet_variant::{Variant, VariantBuilder, VariantMetadataView, 
VariantView};
+/// # use arrow_schema::ArrowError;
+/// # fn main() -> Result<(), ArrowError> {
+/// let mut builder = VariantBuilder::new();
+/// let mut object = builder.new_object();
+/// object.insert("name", "Ferris");
+/// object.new_list("scores").with_value(7i8).with_value(9i8).finish();
+/// object.finish();
+/// let (metadata, value) = builder.finish();
+///
+/// let view = VariantView::try_new(VariantMetadataView::try_new(&metadata)?, 
&value)?;
+/// let scores = view.get_field(b"scores")?.expect("the field exists");
+/// let found = scores.get_index(1)?.expect("the element exists");
+/// assert_eq!(found.to_variant()?, Variant::Int8(9));
+/// assert!(view.get_field(b"missing")?.is_none());
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct VariantView<'m, 'v> {
+    pub(crate) metadata: VariantMetadataView<'m>,
+    pub(crate) value: &'v [u8],
+    header: u8,
+}
+
+impl<'m, 'v> VariantView<'m, 'v> {
+    /// Reads the header byte of the value that starts at the beginning of 
`value`.
+    ///
+    /// `value` may extend past the end of the value.
+    #[inline]
+    pub fn try_new(metadata: VariantMetadataView<'m>, value: &'v [u8]) -> 
Result<Self, ArrowError> {
+        let header = first_byte_from_slice(value)?;
+        Ok(Self {
+            metadata,
+            value,
+            header,
+        })

Review Comment:
   Other than the header byte itself, length validation is deferred until the 
operation that would actually reference the bytes in question?



##########
parquet-variant/src/variant/view.rs:
##########
@@ -0,0 +1,771 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for 
additional information regarding copyright ownership
+// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) 
under one or more contributor license agreements
+
+//! Views over encoded variant bytes that read only what they use. See 
[`VariantView`].
+
+use arrow_schema::ArrowError;
+
+use crate::decoder::{VariantBasicType, get_basic_type};
+use crate::utils::{
+    first_byte_from_slice, overflow_error, slice_from_slice, 
slice_from_slice_at_offset,
+    str_from_bytes, try_binary_search,
+};
+use crate::variant::list::VariantListHeader;
+use crate::variant::metadata::VariantMetadataHeader;
+use crate::variant::object::VariantObjectHeader;
+use crate::variant::{
+    EMPTY_VARIANT_METADATA, Variant, VariantList, VariantMetadata, 
VariantObject,
+};
+
+/// The size of the header byte of a metadata dictionary, object or list.
+const NUM_HEADER_BYTES: u32 = 1;
+
+#[inline]
+fn checked(value: Option<u32>, what: &str) -> Result<u32, ArrowError> {
+    value.ok_or_else(|| overflow_error(what))
+}
+
+fn index_error(kind: &str, index: usize, len: usize) -> ArrowError {
+    ArrowError::InvalidArgumentError(format!(
+        "{kind} index {index} is out of bounds for length {len}"
+    ))
+}
+
+/// A metadata dictionary of which only the header has been read. See 
[`VariantView`].
+#[derive(Debug, Clone, Copy)]
+pub struct VariantMetadataView<'m> {
+    pub(crate) bytes: &'m [u8],
+    pub(crate) header: VariantMetadataHeader,
+    pub(crate) dictionary_size: u32,
+    pub(crate) first_value_byte: u32,
+}
+
+impl<'m> VariantMetadataView<'m> {
+    /// Reads the header and the dictionary size of the metadata dictionary in 
`bytes`.
+    #[inline]
+    pub fn try_new(bytes: &'m [u8]) -> Result<Self, ArrowError> {
+        let header = 
VariantMetadataHeader::try_new(first_byte_from_slice(bytes)?)?;
+        let dictionary_size =
+            header
+                .offset_size
+                .unpack_u32_at_offset(bytes, NUM_HEADER_BYTES as _, 0)?;
+
+        // There are dictionary_size + 1 offsets, and the string bytes 
immediately follow them.
+        let first_value_byte = checked(
+            dictionary_size
+                .checked_add(1)
+                .and_then(|n| n.checked_mul(header.offset_size()))
+                .and_then(|n| n.checked_add(header.first_offset_byte())),
+            "offset of variant metadata dictionary",
+        )?;
+
+        Ok(Self {
+            bytes,
+            header,
+            dictionary_size,
+            first_value_byte,
+        })
+    }
+
+    /// The number of entries in the dictionary.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.dictionary_size as _
+    }
+
+    /// True if the dictionary has no entries.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dictionary_size == 0
+    }
+
+    /// True if the header declares the entries unique and sorted.
+    #[inline]
+    pub fn is_sorted(&self) -> bool {
+        self.header.is_sorted
+    }
+
+    /// The bytes of entry `id`, without UTF-8 validation.
+    #[inline]
+    pub fn entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        if id >= self.len() {
+            return Err(index_error("Metadata dictionary", id, self.len()));
+        }
+        self.read_entry(id)
+    }
+
+    /// The entry `id` as a string.
+    pub fn entry_str(&self, id: usize) -> Result<&'m str, ArrowError> {
+        str_from_bytes(self.entry(id)?)
+    }
+
+    /// The id of the entry equal to `name`, if any.
+    ///
+    /// The search is a binary search if the dictionary is sorted and has more 
than a few entries,
+    /// and a linear scan otherwise.
+    pub fn find(&self, name: &[u8]) -> Result<Option<u32>, ArrowError> {
+        if self.is_sorted() && self.len() > 10 {
+            let found = try_binary_search(self.len(), |id| 
Ok(self.read_entry(id)?.cmp(name)))?;
+            return Ok(found.map(|id| id as u32));
+        }
+        for id in 0..self.len() {
+            if self.read_entry(id)? == name {
+                return Ok(Some(id as u32));
+            }
+        }
+        Ok(None)
+    }
+
+    /// Checks the first and last offsets, and returns the bounded 
[`VariantMetadata`].
+    #[inline]
+    pub fn into_metadata(self) -> Result<VariantMetadata<'m>, ArrowError> {
+        VariantMetadata::try_from_view(self)
+    }
+
+    /// Entry `i` of the offset array, for `i` in `0..=self.len()`.
+    #[inline]
+    pub(crate) fn offset(&self, i: usize) -> Result<u32, ArrowError> {
+        self.header.offset_size.unpack_u32_at_offset(
+            self.bytes,
+            self.header.first_offset_byte() as _,
+            i,
+        )
+    }
+
+    // The bytes of entry `id`, for `id` in `0..self.len()`.
+    #[inline]
+    fn read_entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        let range = self.offset(id)? as usize..self.offset(id + 1)? as usize;
+        slice_from_slice_at_offset(self.bytes, self.first_value_byte as _, 
range)
+    }
+}
+
+/// A variant value of which only the header byte has been read.
+///
+/// Building a view parses one header and nothing else. Each accessor reads 
and bounds-checks only
+/// the bytes it needs, so malformed input produces an error, never a panic. A 
view does not check
+/// UTF-8, sort order, or any offset it does not read. Field names are 
compared as bytes, which
+/// orders them exactly as `str` does.
+///
+/// Use a view to read a few values out of a variant, such as one path per row 
of a column, without
+/// paying for checks that the access does not use.
+///
+/// # Views and validation
+///
+/// The views [`VariantView`], [`VariantMetadataView`], [`VariantObjectView`] 
and
+/// [`VariantListView`] are the weakest state of a variant. The [`Variant`], 
[`VariantMetadata`],
+/// [`VariantObject`] and [`VariantList`] types are the stronger states:
+///
+/// - [`VariantView::to_variant`], [`VariantMetadataView::into_metadata`],
+///   [`VariantObjectView::into_object`] and [`VariantListView::into_list`] 
check the first and
+///   last offsets, which bound the encoding. Unvalidated instances of the 
stronger types guarantee
+///   those checks.
+/// - The `with_full_validation` methods of the stronger types check 
everything else.
+///
+/// # Example
+///
+/// ```
+/// # use parquet_variant::{Variant, VariantBuilder, VariantMetadataView, 
VariantView};
+/// # use arrow_schema::ArrowError;
+/// # fn main() -> Result<(), ArrowError> {
+/// let mut builder = VariantBuilder::new();
+/// let mut object = builder.new_object();
+/// object.insert("name", "Ferris");
+/// object.new_list("scores").with_value(7i8).with_value(9i8).finish();
+/// object.finish();
+/// let (metadata, value) = builder.finish();
+///
+/// let view = VariantView::try_new(VariantMetadataView::try_new(&metadata)?, 
&value)?;
+/// let scores = view.get_field(b"scores")?.expect("the field exists");
+/// let found = scores.get_index(1)?.expect("the element exists");
+/// assert_eq!(found.to_variant()?, Variant::Int8(9));
+/// assert!(view.get_field(b"missing")?.is_none());
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct VariantView<'m, 'v> {
+    pub(crate) metadata: VariantMetadataView<'m>,
+    pub(crate) value: &'v [u8],
+    header: u8,
+}
+
+impl<'m, 'v> VariantView<'m, 'v> {
+    /// Reads the header byte of the value that starts at the beginning of 
`value`.
+    ///
+    /// `value` may extend past the end of the value.
+    #[inline]
+    pub fn try_new(metadata: VariantMetadataView<'m>, value: &'v [u8]) -> 
Result<Self, ArrowError> {
+        let header = first_byte_from_slice(value)?;
+        Ok(Self {
+            metadata,
+            value,
+            header,
+        })
+    }
+
+    /// The metadata dictionary of this value.
+    #[inline]
+    pub fn metadata(&self) -> VariantMetadataView<'m> {
+        self.metadata
+    }
+
+    /// The basic type of this value.
+    #[inline]
+    pub fn basic_type(&self) -> VariantBasicType {
+        get_basic_type(self.header)
+    }
+
+    /// This value as an object, or `None` if it is not an object.
+    pub fn as_object(&self) -> Result<Option<VariantObjectView<'m, 'v>>, 
ArrowError> {
+        match self.basic_type() {
+            VariantBasicType::Object => {
+                VariantObjectView::try_new(self.metadata, self.value).map(Some)
+            }
+            _ => Ok(None),
+        }

Review Comment:
   compact alternative to consider:
   ```suggestion
           (self.basic_type() == VariantBasicType::Object)
               .then(|| VariantObjectView::try_new(self.metadata, self.value))
               .transpose()
   ```
   (more below)



##########
parquet-variant/src/variant/view.rs:
##########
@@ -0,0 +1,771 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for 
additional information regarding copyright ownership
+// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) 
under one or more contributor license agreements
+
+//! Views over encoded variant bytes that read only what they use. See 
[`VariantView`].
+
+use arrow_schema::ArrowError;
+
+use crate::decoder::{VariantBasicType, get_basic_type};
+use crate::utils::{
+    first_byte_from_slice, overflow_error, slice_from_slice, 
slice_from_slice_at_offset,
+    str_from_bytes, try_binary_search,
+};
+use crate::variant::list::VariantListHeader;
+use crate::variant::metadata::VariantMetadataHeader;
+use crate::variant::object::VariantObjectHeader;
+use crate::variant::{
+    EMPTY_VARIANT_METADATA, Variant, VariantList, VariantMetadata, 
VariantObject,
+};
+
+/// The size of the header byte of a metadata dictionary, object or list.
+const NUM_HEADER_BYTES: u32 = 1;
+
+#[inline]
+fn checked(value: Option<u32>, what: &str) -> Result<u32, ArrowError> {
+    value.ok_or_else(|| overflow_error(what))
+}
+
+fn index_error(kind: &str, index: usize, len: usize) -> ArrowError {
+    ArrowError::InvalidArgumentError(format!(
+        "{kind} index {index} is out of bounds for length {len}"
+    ))
+}
+
+/// A metadata dictionary of which only the header has been read. See 
[`VariantView`].
+#[derive(Debug, Clone, Copy)]
+pub struct VariantMetadataView<'m> {
+    pub(crate) bytes: &'m [u8],
+    pub(crate) header: VariantMetadataHeader,
+    pub(crate) dictionary_size: u32,
+    pub(crate) first_value_byte: u32,
+}
+
+impl<'m> VariantMetadataView<'m> {
+    /// Reads the header and the dictionary size of the metadata dictionary in 
`bytes`.
+    #[inline]
+    pub fn try_new(bytes: &'m [u8]) -> Result<Self, ArrowError> {
+        let header = 
VariantMetadataHeader::try_new(first_byte_from_slice(bytes)?)?;
+        let dictionary_size =
+            header
+                .offset_size
+                .unpack_u32_at_offset(bytes, NUM_HEADER_BYTES as _, 0)?;
+
+        // There are dictionary_size + 1 offsets, and the string bytes 
immediately follow them.
+        let first_value_byte = checked(
+            dictionary_size
+                .checked_add(1)
+                .and_then(|n| n.checked_mul(header.offset_size()))
+                .and_then(|n| n.checked_add(header.first_offset_byte())),
+            "offset of variant metadata dictionary",
+        )?;
+
+        Ok(Self {
+            bytes,
+            header,
+            dictionary_size,
+            first_value_byte,
+        })
+    }
+
+    /// The number of entries in the dictionary.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.dictionary_size as _
+    }
+
+    /// True if the dictionary has no entries.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dictionary_size == 0
+    }
+
+    /// True if the header declares the entries unique and sorted.
+    #[inline]
+    pub fn is_sorted(&self) -> bool {
+        self.header.is_sorted
+    }
+
+    /// The bytes of entry `id`, without UTF-8 validation.
+    #[inline]
+    pub fn entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        if id >= self.len() {
+            return Err(index_error("Metadata dictionary", id, self.len()));
+        }
+        self.read_entry(id)
+    }
+
+    /// The entry `id` as a string.
+    pub fn entry_str(&self, id: usize) -> Result<&'m str, ArrowError> {
+        str_from_bytes(self.entry(id)?)
+    }
+
+    /// The id of the entry equal to `name`, if any.
+    ///
+    /// The search is a binary search if the dictionary is sorted and has more 
than a few entries,
+    /// and a linear scan otherwise.
+    pub fn find(&self, name: &[u8]) -> Result<Option<u32>, ArrowError> {
+        if self.is_sorted() && self.len() > 10 {
+            let found = try_binary_search(self.len(), |id| 
Ok(self.read_entry(id)?.cmp(name)))?;
+            return Ok(found.map(|id| id as u32));
+        }
+        for id in 0..self.len() {
+            if self.read_entry(id)? == name {
+                return Ok(Some(id as u32));
+            }
+        }
+        Ok(None)
+    }
+
+    /// Checks the first and last offsets, and returns the bounded 
[`VariantMetadata`].
+    #[inline]
+    pub fn into_metadata(self) -> Result<VariantMetadata<'m>, ArrowError> {
+        VariantMetadata::try_from_view(self)
+    }
+
+    /// Entry `i` of the offset array, for `i` in `0..=self.len()`.
+    #[inline]
+    pub(crate) fn offset(&self, i: usize) -> Result<u32, ArrowError> {
+        self.header.offset_size.unpack_u32_at_offset(
+            self.bytes,
+            self.header.first_offset_byte() as _,
+            i,
+        )
+    }
+
+    // The bytes of entry `id`, for `id` in `0..self.len()`.
+    #[inline]
+    fn read_entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        let range = self.offset(id)? as usize..self.offset(id + 1)? as usize;
+        slice_from_slice_at_offset(self.bytes, self.first_value_byte as _, 
range)
+    }
+}
+
+/// A variant value of which only the header byte has been read.
+///
+/// Building a view parses one header and nothing else. Each accessor reads 
and bounds-checks only
+/// the bytes it needs, so malformed input produces an error, never a panic. A 
view does not check
+/// UTF-8, sort order, or any offset it does not read. Field names are 
compared as bytes, which
+/// orders them exactly as `str` does.
+///
+/// Use a view to read a few values out of a variant, such as one path per row 
of a column, without
+/// paying for checks that the access does not use.
+///
+/// # Views and validation
+///
+/// The views [`VariantView`], [`VariantMetadataView`], [`VariantObjectView`] 
and
+/// [`VariantListView`] are the weakest state of a variant. The [`Variant`], 
[`VariantMetadata`],
+/// [`VariantObject`] and [`VariantList`] types are the stronger states:
+///
+/// - [`VariantView::to_variant`], [`VariantMetadataView::into_metadata`],
+///   [`VariantObjectView::into_object`] and [`VariantListView::into_list`] 
check the first and
+///   last offsets, which bound the encoding. Unvalidated instances of the 
stronger types guarantee
+///   those checks.
+/// - The `with_full_validation` methods of the stronger types check 
everything else.
+///
+/// # Example
+///
+/// ```
+/// # use parquet_variant::{Variant, VariantBuilder, VariantMetadataView, 
VariantView};
+/// # use arrow_schema::ArrowError;
+/// # fn main() -> Result<(), ArrowError> {
+/// let mut builder = VariantBuilder::new();
+/// let mut object = builder.new_object();
+/// object.insert("name", "Ferris");
+/// object.new_list("scores").with_value(7i8).with_value(9i8).finish();
+/// object.finish();
+/// let (metadata, value) = builder.finish();
+///
+/// let view = VariantView::try_new(VariantMetadataView::try_new(&metadata)?, 
&value)?;
+/// let scores = view.get_field(b"scores")?.expect("the field exists");
+/// let found = scores.get_index(1)?.expect("the element exists");
+/// assert_eq!(found.to_variant()?, Variant::Int8(9));
+/// assert!(view.get_field(b"missing")?.is_none());
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct VariantView<'m, 'v> {
+    pub(crate) metadata: VariantMetadataView<'m>,
+    pub(crate) value: &'v [u8],
+    header: u8,
+}
+
+impl<'m, 'v> VariantView<'m, 'v> {
+    /// Reads the header byte of the value that starts at the beginning of 
`value`.
+    ///
+    /// `value` may extend past the end of the value.
+    #[inline]
+    pub fn try_new(metadata: VariantMetadataView<'m>, value: &'v [u8]) -> 
Result<Self, ArrowError> {
+        let header = first_byte_from_slice(value)?;
+        Ok(Self {
+            metadata,
+            value,
+            header,
+        })
+    }
+
+    /// The metadata dictionary of this value.
+    #[inline]
+    pub fn metadata(&self) -> VariantMetadataView<'m> {
+        self.metadata
+    }
+
+    /// The basic type of this value.
+    #[inline]
+    pub fn basic_type(&self) -> VariantBasicType {
+        get_basic_type(self.header)
+    }
+
+    /// This value as an object, or `None` if it is not an object.
+    pub fn as_object(&self) -> Result<Option<VariantObjectView<'m, 'v>>, 
ArrowError> {
+        match self.basic_type() {
+            VariantBasicType::Object => {
+                VariantObjectView::try_new(self.metadata, self.value).map(Some)
+            }
+            _ => Ok(None),
+        }
+    }
+
+    /// This value as a list, or `None` if it is not a list.
+    pub fn as_list(&self) -> Result<Option<VariantListView<'m, 'v>>, 
ArrowError> {
+        match self.basic_type() {
+            VariantBasicType::Array => {
+                VariantListView::try_new(self.metadata, self.value).map(Some)
+            }
+            _ => Ok(None),
+        }
+    }
+
+    /// The value of field `name`, or `None` if this value is not an object or 
has no such field.
+    pub fn get_field(&self, name: &[u8]) -> Result<Option<Self>, ArrowError> {
+        match self.as_object()? {
+            Some(object) => object.get(name),
+            None => Ok(None),
+        }
+    }
+
+    /// Element `index`, or `None` if this value is not a list or has no such 
element.
+    pub fn get_index(&self, index: usize) -> Result<Option<Self>, ArrowError> {
+        match self.as_list()? {
+            Some(list) => list.get(index),
+            None => Ok(None),
+        }
+    }
+
+    /// Decodes this value as an unvalidated [`Variant`].
+    ///
+    /// Only an object or a list reads the metadata dictionary, so only they 
check its bounds.
+    #[inline]
+    pub fn to_variant(&self) -> Result<Variant<'m, 'v>, ArrowError> {
+        let metadata = match self.basic_type() {
+            VariantBasicType::Object | VariantBasicType::Array => 
self.metadata.into_metadata()?,
+            VariantBasicType::Primitive | VariantBasicType::ShortString => 
EMPTY_VARIANT_METADATA,
+        };
+        Variant::try_new_with_metadata_and_shallow_validation(metadata, 
self.value)
+    }
+}
+
+/// A variant object of which only the header has been read. See 
[`VariantView`].
+#[derive(Debug, Clone, Copy)]
+pub struct VariantObjectView<'m, 'v> {
+    pub(crate) metadata: VariantMetadataView<'m>,
+    pub(crate) value: &'v [u8],
+    pub(crate) header: VariantObjectHeader,
+    pub(crate) num_elements: u32,
+    pub(crate) first_field_offset_byte: u32,
+    pub(crate) first_value_byte: u32,
+}
+
+impl<'m, 'v> VariantObjectView<'m, 'v> {
+    /// Reads the header and the field count of the object at the start of 
`value`.
+    #[inline]
+    pub fn try_new(metadata: VariantMetadataView<'m>, value: &'v [u8]) -> 
Result<Self, ArrowError> {
+        let header = 
VariantObjectHeader::try_new(first_byte_from_slice(value)?)?;
+        let num_elements =
+            header
+                .num_elements_size
+                .unpack_u32_at_offset(value, NUM_HEADER_BYTES as _, 0)?;
+
+        let first_field_offset_byte = checked(
+            num_elements
+                .checked_mul(header.field_id_size())
+                .and_then(|n| n.checked_add(header.field_ids_start_byte())),
+            "offset of variant object field offsets",
+        )?;
+        let first_value_byte = checked(
+            num_elements
+                .checked_add(1)
+                .and_then(|n| n.checked_mul(header.field_offset_size()))
+                .and_then(|n| n.checked_add(first_field_offset_byte)),
+            "offset of variant object field values",
+        )?;
+
+        Ok(Self {
+            metadata,
+            value,
+            header,
+            num_elements,
+            first_field_offset_byte,
+            first_value_byte,
+        })
+    }
+
+    /// The number of fields.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.num_elements as _
+    }
+
+    /// True if the object has no fields.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.num_elements == 0
+    }
+
+    /// The metadata dictionary id of field `i`.
+    pub fn field_id(&self, i: usize) -> Result<u32, ArrowError> {
+        self.check_index(i)?;
+        self.read_field_id(i)
+    }
+
+    /// The name of field `i`, without UTF-8 validation.
+    pub fn field_name(&self, i: usize) -> Result<&'m [u8], ArrowError> {
+        self.check_index(i)?;
+        self.read_field_name(i)
+    }
+
+    /// The value of field `i`.
+    pub fn field(&self, i: usize) -> Result<VariantView<'m, 'v>, ArrowError> {
+        self.check_index(i)?;
+        self.read_field(i)
+    }
+
+    /// The position of the field named `name`, if any.
+    ///
+    /// The spec requires fields to be sorted by name, so this is a binary 
search.
+    pub fn find(&self, name: &[u8]) -> Result<Option<usize>, ArrowError> {
+        try_binary_search(self.len(), |i| 
Ok(self.read_field_name(i)?.cmp(name)))
+    }
+
+    /// The value of the field named `name`, if any.
+    pub fn get(&self, name: &[u8]) -> Result<Option<VariantView<'m, 'v>>, 
ArrowError> {
+        self.find(name)?.map(|i| self.read_field(i)).transpose()
+    }
+
+    /// The size of the encoded object.
+    ///
+    /// The spec makes the last field offset point one byte past the end of 
the last value.
+    pub fn byte_len(&self) -> Result<usize, ArrowError> {
+        let end = checked(
+            self.read_offset(self.len())?
+                .checked_add(self.first_value_byte),
+            "variant object size",
+        )?;
+        Ok(end as _)
+    }
+
+    /// Checks the last field offset, and returns the bounded 
[`VariantObject`] that uses
+    /// `metadata`, the promoted form of this view's metadata dictionary.
+    #[inline]
+    pub fn into_object(
+        self,
+        metadata: VariantMetadata<'m>,
+    ) -> Result<VariantObject<'m, 'v>, ArrowError> {
+        VariantObject::try_from_view(self, metadata)
+    }
+
+    #[inline]
+    fn check_index(&self, i: usize) -> Result<(), ArrowError> {
+        match i < self.len() {
+            true => Ok(()),
+            false => Err(index_error("Variant object field", i, self.len())),
+        }

Review Comment:
   aside: It will be nice to have 
[bool.ok_or_else](https://doc.rust-lang.org/std/primitive.bool.html#method.ok_or_else)
 once MSRV bumps to 1.98:
   
   ```rust
   (i < self.len()).ok_or_else(|| index_error("Variant object field", i, 
self.len()))
   ```
   (some day, not now)



##########
parquet-variant/src/variant/view.rs:
##########
@@ -0,0 +1,771 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for 
additional information regarding copyright ownership
+// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) 
under one or more contributor license agreements
+
+//! Views over encoded variant bytes that read only what they use. See 
[`VariantView`].
+
+use arrow_schema::ArrowError;
+
+use crate::decoder::{VariantBasicType, get_basic_type};
+use crate::utils::{
+    first_byte_from_slice, overflow_error, slice_from_slice, 
slice_from_slice_at_offset,
+    str_from_bytes, try_binary_search,
+};
+use crate::variant::list::VariantListHeader;
+use crate::variant::metadata::VariantMetadataHeader;
+use crate::variant::object::VariantObjectHeader;
+use crate::variant::{
+    EMPTY_VARIANT_METADATA, Variant, VariantList, VariantMetadata, 
VariantObject,
+};
+
+/// The size of the header byte of a metadata dictionary, object or list.
+const NUM_HEADER_BYTES: u32 = 1;
+
+#[inline]
+fn checked(value: Option<u32>, what: &str) -> Result<u32, ArrowError> {
+    value.ok_or_else(|| overflow_error(what))
+}
+
+fn index_error(kind: &str, index: usize, len: usize) -> ArrowError {
+    ArrowError::InvalidArgumentError(format!(
+        "{kind} index {index} is out of bounds for length {len}"
+    ))
+}
+
+/// A metadata dictionary of which only the header has been read. See 
[`VariantView`].
+#[derive(Debug, Clone, Copy)]
+pub struct VariantMetadataView<'m> {
+    pub(crate) bytes: &'m [u8],
+    pub(crate) header: VariantMetadataHeader,
+    pub(crate) dictionary_size: u32,
+    pub(crate) first_value_byte: u32,
+}
+
+impl<'m> VariantMetadataView<'m> {
+    /// Reads the header and the dictionary size of the metadata dictionary in 
`bytes`.
+    #[inline]
+    pub fn try_new(bytes: &'m [u8]) -> Result<Self, ArrowError> {
+        let header = 
VariantMetadataHeader::try_new(first_byte_from_slice(bytes)?)?;
+        let dictionary_size =
+            header
+                .offset_size
+                .unpack_u32_at_offset(bytes, NUM_HEADER_BYTES as _, 0)?;
+
+        // There are dictionary_size + 1 offsets, and the string bytes 
immediately follow them.
+        let first_value_byte = checked(
+            dictionary_size
+                .checked_add(1)
+                .and_then(|n| n.checked_mul(header.offset_size()))
+                .and_then(|n| n.checked_add(header.first_offset_byte())),
+            "offset of variant metadata dictionary",
+        )?;
+
+        Ok(Self {
+            bytes,
+            header,
+            dictionary_size,
+            first_value_byte,
+        })
+    }
+
+    /// The number of entries in the dictionary.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.dictionary_size as _
+    }
+
+    /// True if the dictionary has no entries.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dictionary_size == 0
+    }
+
+    /// True if the header declares the entries unique and sorted.
+    #[inline]
+    pub fn is_sorted(&self) -> bool {
+        self.header.is_sorted
+    }
+
+    /// The bytes of entry `id`, without UTF-8 validation.
+    #[inline]
+    pub fn entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        if id >= self.len() {
+            return Err(index_error("Metadata dictionary", id, self.len()));
+        }
+        self.read_entry(id)
+    }
+
+    /// The entry `id` as a string.
+    pub fn entry_str(&self, id: usize) -> Result<&'m str, ArrowError> {
+        str_from_bytes(self.entry(id)?)
+    }
+
+    /// The id of the entry equal to `name`, if any.
+    ///
+    /// The search is a binary search if the dictionary is sorted and has more 
than a few entries,
+    /// and a linear scan otherwise.
+    pub fn find(&self, name: &[u8]) -> Result<Option<u32>, ArrowError> {
+        if self.is_sorted() && self.len() > 10 {
+            let found = try_binary_search(self.len(), |id| 
Ok(self.read_entry(id)?.cmp(name)))?;
+            return Ok(found.map(|id| id as u32));
+        }
+        for id in 0..self.len() {
+            if self.read_entry(id)? == name {
+                return Ok(Some(id as u32));
+            }
+        }
+        Ok(None)
+    }
+
+    /// Checks the first and last offsets, and returns the bounded 
[`VariantMetadata`].
+    #[inline]
+    pub fn into_metadata(self) -> Result<VariantMetadata<'m>, ArrowError> {
+        VariantMetadata::try_from_view(self)
+    }
+
+    /// Entry `i` of the offset array, for `i` in `0..=self.len()`.
+    #[inline]
+    pub(crate) fn offset(&self, i: usize) -> Result<u32, ArrowError> {
+        self.header.offset_size.unpack_u32_at_offset(
+            self.bytes,
+            self.header.first_offset_byte() as _,
+            i,
+        )
+    }
+
+    // The bytes of entry `id`, for `id` in `0..self.len()`.
+    #[inline]
+    fn read_entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        let range = self.offset(id)? as usize..self.offset(id + 1)? as usize;
+        slice_from_slice_at_offset(self.bytes, self.first_value_byte as _, 
range)
+    }
+}
+
+/// A variant value of which only the header byte has been read.

Review Comment:
   Should [some of] this be hoisted to a mod doc comment since the concepts 
apply to all four variant building blocks (value, object, list, metadata)?



##########
parquet-variant/src/variant/view.rs:
##########
@@ -0,0 +1,771 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for 
additional information regarding copyright ownership
+// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) 
under one or more contributor license agreements
+
+//! Views over encoded variant bytes that read only what they use. See 
[`VariantView`].
+
+use arrow_schema::ArrowError;
+
+use crate::decoder::{VariantBasicType, get_basic_type};
+use crate::utils::{
+    first_byte_from_slice, overflow_error, slice_from_slice, 
slice_from_slice_at_offset,
+    str_from_bytes, try_binary_search,
+};
+use crate::variant::list::VariantListHeader;
+use crate::variant::metadata::VariantMetadataHeader;
+use crate::variant::object::VariantObjectHeader;
+use crate::variant::{
+    EMPTY_VARIANT_METADATA, Variant, VariantList, VariantMetadata, 
VariantObject,
+};
+
+/// The size of the header byte of a metadata dictionary, object or list.
+const NUM_HEADER_BYTES: u32 = 1;
+
+#[inline]
+fn checked(value: Option<u32>, what: &str) -> Result<u32, ArrowError> {
+    value.ok_or_else(|| overflow_error(what))
+}
+
+fn index_error(kind: &str, index: usize, len: usize) -> ArrowError {
+    ArrowError::InvalidArgumentError(format!(
+        "{kind} index {index} is out of bounds for length {len}"
+    ))
+}
+
+/// A metadata dictionary of which only the header has been read. See 
[`VariantView`].
+#[derive(Debug, Clone, Copy)]
+pub struct VariantMetadataView<'m> {
+    pub(crate) bytes: &'m [u8],
+    pub(crate) header: VariantMetadataHeader,
+    pub(crate) dictionary_size: u32,
+    pub(crate) first_value_byte: u32,
+}
+
+impl<'m> VariantMetadataView<'m> {
+    /// Reads the header and the dictionary size of the metadata dictionary in 
`bytes`.
+    #[inline]
+    pub fn try_new(bytes: &'m [u8]) -> Result<Self, ArrowError> {
+        let header = 
VariantMetadataHeader::try_new(first_byte_from_slice(bytes)?)?;
+        let dictionary_size =
+            header
+                .offset_size
+                .unpack_u32_at_offset(bytes, NUM_HEADER_BYTES as _, 0)?;
+
+        // There are dictionary_size + 1 offsets, and the string bytes 
immediately follow them.
+        let first_value_byte = checked(
+            dictionary_size
+                .checked_add(1)
+                .and_then(|n| n.checked_mul(header.offset_size()))
+                .and_then(|n| n.checked_add(header.first_offset_byte())),
+            "offset of variant metadata dictionary",
+        )?;
+
+        Ok(Self {
+            bytes,
+            header,
+            dictionary_size,
+            first_value_byte,
+        })
+    }
+
+    /// The number of entries in the dictionary.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.dictionary_size as _
+    }
+
+    /// True if the dictionary has no entries.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dictionary_size == 0
+    }
+
+    /// True if the header declares the entries unique and sorted.
+    #[inline]
+    pub fn is_sorted(&self) -> bool {
+        self.header.is_sorted
+    }
+
+    /// The bytes of entry `id`, without UTF-8 validation.
+    #[inline]
+    pub fn entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        if id >= self.len() {
+            return Err(index_error("Metadata dictionary", id, self.len()));
+        }
+        self.read_entry(id)
+    }
+
+    /// The entry `id` as a string.
+    pub fn entry_str(&self, id: usize) -> Result<&'m str, ArrowError> {
+        str_from_bytes(self.entry(id)?)
+    }
+
+    /// The id of the entry equal to `name`, if any.
+    ///
+    /// The search is a binary search if the dictionary is sorted and has more 
than a few entries,
+    /// and a linear scan otherwise.
+    pub fn find(&self, name: &[u8]) -> Result<Option<u32>, ArrowError> {
+        if self.is_sorted() && self.len() > 10 {
+            let found = try_binary_search(self.len(), |id| 
Ok(self.read_entry(id)?.cmp(name)))?;
+            return Ok(found.map(|id| id as u32));
+        }
+        for id in 0..self.len() {
+            if self.read_entry(id)? == name {
+                return Ok(Some(id as u32));
+            }
+        }
+        Ok(None)
+    }
+
+    /// Checks the first and last offsets, and returns the bounded 
[`VariantMetadata`].
+    #[inline]
+    pub fn into_metadata(self) -> Result<VariantMetadata<'m>, ArrowError> {
+        VariantMetadata::try_from_view(self)
+    }
+
+    /// Entry `i` of the offset array, for `i` in `0..=self.len()`.
+    #[inline]
+    pub(crate) fn offset(&self, i: usize) -> Result<u32, ArrowError> {
+        self.header.offset_size.unpack_u32_at_offset(
+            self.bytes,
+            self.header.first_offset_byte() as _,
+            i,
+        )
+    }
+
+    // The bytes of entry `id`, for `id` in `0..self.len()`.
+    #[inline]
+    fn read_entry(&self, id: usize) -> Result<&'m [u8], ArrowError> {
+        let range = self.offset(id)? as usize..self.offset(id + 1)? as usize;
+        slice_from_slice_at_offset(self.bytes, self.first_value_byte as _, 
range)
+    }
+}
+
+/// A variant value of which only the header byte has been read.
+///
+/// Building a view parses one header and nothing else. Each accessor reads 
and bounds-checks only
+/// the bytes it needs, so malformed input produces an error, never a panic. A 
view does not check
+/// UTF-8, sort order, or any offset it does not read. Field names are 
compared as bytes, which
+/// orders them exactly as `str` does.
+///
+/// Use a view to read a few values out of a variant, such as one path per row 
of a column, without
+/// paying for checks that the access does not use.
+///
+/// # Views and validation
+///
+/// The views [`VariantView`], [`VariantMetadataView`], [`VariantObjectView`] 
and
+/// [`VariantListView`] are the weakest state of a variant. The [`Variant`], 
[`VariantMetadata`],
+/// [`VariantObject`] and [`VariantList`] types are the stronger states:
+///
+/// - [`VariantView::to_variant`], [`VariantMetadataView::into_metadata`],
+///   [`VariantObjectView::into_object`] and [`VariantListView::into_list`] 
check the first and
+///   last offsets, which bound the encoding. Unvalidated instances of the 
stronger types guarantee
+///   those checks.
+/// - The `with_full_validation` methods of the stronger types check 
everything else.
+///
+/// # Example
+///
+/// ```
+/// # use parquet_variant::{Variant, VariantBuilder, VariantMetadataView, 
VariantView};
+/// # use arrow_schema::ArrowError;
+/// # fn main() -> Result<(), ArrowError> {
+/// let mut builder = VariantBuilder::new();
+/// let mut object = builder.new_object();
+/// object.insert("name", "Ferris");
+/// object.new_list("scores").with_value(7i8).with_value(9i8).finish();
+/// object.finish();
+/// let (metadata, value) = builder.finish();
+///
+/// let view = VariantView::try_new(VariantMetadataView::try_new(&metadata)?, 
&value)?;
+/// let scores = view.get_field(b"scores")?.expect("the field exists");
+/// let found = scores.get_index(1)?.expect("the element exists");
+/// assert_eq!(found.to_variant()?, Variant::Int8(9));
+/// assert!(view.get_field(b"missing")?.is_none());
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct VariantView<'m, 'v> {
+    pub(crate) metadata: VariantMetadataView<'m>,
+    pub(crate) value: &'v [u8],
+    header: u8,
+}
+
+impl<'m, 'v> VariantView<'m, 'v> {
+    /// Reads the header byte of the value that starts at the beginning of 
`value`.
+    ///
+    /// `value` may extend past the end of the value.
+    #[inline]
+    pub fn try_new(metadata: VariantMetadataView<'m>, value: &'v [u8]) -> 
Result<Self, ArrowError> {
+        let header = first_byte_from_slice(value)?;
+        Ok(Self {
+            metadata,
+            value,
+            header,
+        })
+    }
+
+    /// The metadata dictionary of this value.
+    #[inline]
+    pub fn metadata(&self) -> VariantMetadataView<'m> {
+        self.metadata
+    }
+
+    /// The basic type of this value.
+    #[inline]
+    pub fn basic_type(&self) -> VariantBasicType {
+        get_basic_type(self.header)
+    }
+
+    /// This value as an object, or `None` if it is not an object.
+    pub fn as_object(&self) -> Result<Option<VariantObjectView<'m, 'v>>, 
ArrowError> {
+        match self.basic_type() {
+            VariantBasicType::Object => {
+                VariantObjectView::try_new(self.metadata, self.value).map(Some)
+            }
+            _ => Ok(None),
+        }
+    }
+
+    /// This value as a list, or `None` if it is not a list.
+    pub fn as_list(&self) -> Result<Option<VariantListView<'m, 'v>>, 
ArrowError> {
+        match self.basic_type() {
+            VariantBasicType::Array => {
+                VariantListView::try_new(self.metadata, self.value).map(Some)
+            }
+            _ => Ok(None),
+        }
+    }
+
+    /// The value of field `name`, or `None` if this value is not an object or 
has no such field.
+    pub fn get_field(&self, name: &[u8]) -> Result<Option<Self>, ArrowError> {
+        match self.as_object()? {
+            Some(object) => object.get(name),
+            None => Ok(None),
+        }
+    }
+
+    /// Element `index`, or `None` if this value is not a list or has no such 
element.
+    pub fn get_index(&self, index: usize) -> Result<Option<Self>, ArrowError> {
+        match self.as_list()? {
+            Some(list) => list.get(index),
+            None => Ok(None),
+        }
+    }
+
+    /// Decodes this value as an unvalidated [`Variant`].
+    ///
+    /// Only an object or a list reads the metadata dictionary, so only they 
check its bounds.
+    #[inline]
+    pub fn to_variant(&self) -> Result<Variant<'m, 'v>, ArrowError> {
+        let metadata = match self.basic_type() {
+            VariantBasicType::Object | VariantBasicType::Array => 
self.metadata.into_metadata()?,
+            VariantBasicType::Primitive | VariantBasicType::ShortString => 
EMPTY_VARIANT_METADATA,
+        };
+        Variant::try_new_with_metadata_and_shallow_validation(metadata, 
self.value)
+    }
+}
+
+/// A variant object of which only the header has been read. See 
[`VariantView`].
+#[derive(Debug, Clone, Copy)]
+pub struct VariantObjectView<'m, 'v> {
+    pub(crate) metadata: VariantMetadataView<'m>,
+    pub(crate) value: &'v [u8],
+    pub(crate) header: VariantObjectHeader,
+    pub(crate) num_elements: u32,
+    pub(crate) first_field_offset_byte: u32,
+    pub(crate) first_value_byte: u32,
+}
+
+impl<'m, 'v> VariantObjectView<'m, 'v> {
+    /// Reads the header and the field count of the object at the start of 
`value`.
+    #[inline]
+    pub fn try_new(metadata: VariantMetadataView<'m>, value: &'v [u8]) -> 
Result<Self, ArrowError> {
+        let header = 
VariantObjectHeader::try_new(first_byte_from_slice(value)?)?;
+        let num_elements =
+            header
+                .num_elements_size
+                .unpack_u32_at_offset(value, NUM_HEADER_BYTES as _, 0)?;
+
+        let first_field_offset_byte = checked(
+            num_elements
+                .checked_mul(header.field_id_size())
+                .and_then(|n| n.checked_add(header.field_ids_start_byte())),
+            "offset of variant object field offsets",
+        )?;
+        let first_value_byte = checked(
+            num_elements
+                .checked_add(1)
+                .and_then(|n| n.checked_mul(header.field_offset_size()))
+                .and_then(|n| n.checked_add(first_field_offset_byte)),
+            "offset of variant object field values",
+        )?;
+
+        Ok(Self {
+            metadata,
+            value,
+            header,
+            num_elements,
+            first_field_offset_byte,
+            first_value_byte,
+        })
+    }
+
+    /// The number of fields.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.num_elements as _
+    }
+
+    /// True if the object has no fields.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.num_elements == 0
+    }
+
+    /// The metadata dictionary id of field `i`.
+    pub fn field_id(&self, i: usize) -> Result<u32, ArrowError> {
+        self.check_index(i)?;
+        self.read_field_id(i)
+    }
+
+    /// The name of field `i`, without UTF-8 validation.
+    pub fn field_name(&self, i: usize) -> Result<&'m [u8], ArrowError> {
+        self.check_index(i)?;
+        self.read_field_name(i)
+    }
+
+    /// The value of field `i`.
+    pub fn field(&self, i: usize) -> Result<VariantView<'m, 'v>, ArrowError> {
+        self.check_index(i)?;
+        self.read_field(i)
+    }
+
+    /// The position of the field named `name`, if any.
+    ///
+    /// The spec requires fields to be sorted by name, so this is a binary 
search.
+    pub fn find(&self, name: &[u8]) -> Result<Option<usize>, ArrowError> {
+        try_binary_search(self.len(), |i| 
Ok(self.read_field_name(i)?.cmp(name)))
+    }
+
+    /// The value of the field named `name`, if any.
+    pub fn get(&self, name: &[u8]) -> Result<Option<VariantView<'m, 'v>>, 
ArrowError> {
+        self.find(name)?.map(|i| self.read_field(i)).transpose()
+    }
+
+    /// The size of the encoded object.
+    ///
+    /// The spec makes the last field offset point one byte past the end of 
the last value.
+    pub fn byte_len(&self) -> Result<usize, ArrowError> {
+        let end = checked(
+            self.read_offset(self.len())?
+                .checked_add(self.first_value_byte),
+            "variant object size",
+        )?;
+        Ok(end as _)
+    }
+
+    /// Checks the last field offset, and returns the bounded 
[`VariantObject`] that uses
+    /// `metadata`, the promoted form of this view's metadata dictionary.

Review Comment:
   Not directly, but every `VariantObject` has a metadata inside it, that had 
to come from somewhere.
   
   But I don't know how the "promoted form" part relates, and the error spec is 
vague at best. Perhaps better to just say something like this?
   ```rust 
   /// Attempts to interpret this view and `metadata` as a 
   /// [validated][`VariantObject::try_new#validation`] `VariantObject`
   ```
   
   (matches the wording of the linked `VariantObject` constructor)



##########
parquet-variant/src/utils.rs:
##########
@@ -93,6 +94,25 @@ pub(crate) fn str_from_bytes(bytes: &[u8]) -> Result<&str, 
ArrowError> {
         .map_err(|_| ArrowError::InvalidArgumentError("invalid UTF-8 
string".to_string()))
 }
 
+/// Binary search over `0..len` with a fallible comparison, which returns the 
first error it hits.
+///
+/// Returns the index for which `cmp` returns [`Ordering::Equal`], if any.
+pub(crate) fn try_binary_search(

Review Comment:
   This is a near copy of `try_binary_search_range_by` below, differing only in:
   * Explicit start..end vs. implied 0..len
   * Comparator fallibility expressed differently (Result vs. Option)
   * Result/Option vs. Option/Result return value
   * Not-found None vs. Err
   
   What is the significance of these differences? Can we somehow harmonize the 
two?



##########
parquet-variant/src/utils.rs:
##########
@@ -93,6 +94,25 @@ pub(crate) fn str_from_bytes(bytes: &[u8]) -> Result<&str, 
ArrowError> {
         .map_err(|_| ArrowError::InvalidArgumentError("invalid UTF-8 
string".to_string()))
 }
 
+/// Binary search over `0..len` with a fallible comparison, which returns the 
first error it hits.
+///
+/// Returns the index for which `cmp` returns [`Ordering::Equal`], if any.
+pub(crate) fn try_binary_search(

Review Comment:
   AFAICT, the new function has superior semantics (returns the actual error 
from a failed comparison) and none of the old function's call sites actually 
rely on the `Some(Err(insertion_point))` it so carefully returns. Recommend 
delete the old method and take over its name.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to