diff --git a/parquet-variant/src/builder.rs b/parquet-variant/src/builder.rs index fe3090f70b8f..cb3a373cb832 100644 --- a/parquet-variant/src/builder.rs +++ b/parquet-variant/src/builder.rs @@ -450,6 +450,7 @@ impl MetadataBuilder { /// obj.insert("a", 1); /// obj.insert("a", 2); // duplicate field /// +/// // When validation is enabled, finish will return an error /// let result = obj.finish(); // returns Err /// assert!(result.is_err()); /// ``` @@ -495,10 +496,20 @@ impl VariantBuilder { .with_validate_unique_fields(self.validate_unique_fields) } + /// Append a non-nested value to the builder. + /// + /// # Example + /// ``` + /// # use parquet_variant::{Variant, VariantBuilder}; + /// let mut builder = VariantBuilder::new(); + /// // most primitive types can be appended directly as they implement `Into` + /// builder.append_value(42i8); + /// ``` pub fn append_value<'m, 'd, T: Into>>(&mut self, value: T) { self.buffer.append_non_nested_value(value); } + /// Finish the builder and return the metadata and value buffers. pub fn finish(self) -> (Vec, Vec) { (self.metadata_builder.finish(), self.buffer.into_inner()) } @@ -577,6 +588,7 @@ impl<'a> ListBuilder<'a> { self.offsets.push(element_end); } + /// Finish the list, writing it to the parent buffer and consuming self. pub fn finish(mut self) { self.check_new_offset(); @@ -603,6 +615,14 @@ impl<'a> ListBuilder<'a> { } } +/// Drop implementation for ListBuilder does nothing +/// as the `finish` method must be called to finalize the list. +/// This is to ensure that the list is always finalized before its parent builder +/// is finalized. +impl Drop for ListBuilder<'_> { + fn drop(&mut self) {} +} + /// A builder for creating [`Variant::Object`] values. /// /// See the examples on [`VariantBuilder`] for usage. @@ -694,9 +714,7 @@ impl<'a, 'b> ObjectBuilder<'a, 'b> { list_builder } - /// Finalize object - /// - /// This consumes self and writes the object to the parent buffer. + /// Finalize the object, writing it to the parent buffer and consuming self. pub fn finish(mut self) -> Result<(), ArrowError> { self.check_pending_field(); @@ -756,6 +774,14 @@ impl<'a, 'b> ObjectBuilder<'a, 'b> { } } +/// Drop implementation for ObjectBuilder does nothing +/// as the `finish` method must be called to finalize the object. +/// This is to ensure that the object is always finalized before its parent builder +/// is finalized. +impl Drop for ObjectBuilder<'_, '_> { + fn drop(&mut self) {} +} + /// Trait that abstracts functionality from Variant fconstruction implementations, namely /// `VariantBuilder`, `ListBuilder` and `ObjectFieldBuilder` to minimize code duplication. pub(crate) trait VariantBuilderExt<'m, 'v> { @@ -1490,6 +1516,9 @@ mod tests { "Invalid argument error: Duplicate field keys detected: [x]" ); + inner_list.finish(); + outer_list.finish(); + // Valid object should succeed let mut list = builder.new_list(); let mut valid_obj = list.new_object();