Skip to main content

parquet_variant/builder/
object.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use crate::builder::list::ListBuilder;
6use crate::builder::metadata::MetadataBuilder;
7use crate::decoder::VariantBasicType;
8use crate::{
9    BASIC_TYPE_BITS, BuilderSpecificState, ParentState, ValueBuilder, Variant, VariantBuilderExt,
10    int_size,
11};
12use arrow_schema::ArrowError;
13use indexmap::{IndexMap, map::Entry};
14
15fn object_header<const LARGE_BIT: u8, const ID_SIZE: u8, const OFFSET_SIZE: u8>() -> u8 {
16    (LARGE_BIT << (BASIC_TYPE_BITS + 4))
17        | ((ID_SIZE - 1) << (BASIC_TYPE_BITS + 2))
18        | ((OFFSET_SIZE - 1) << BASIC_TYPE_BITS)
19        | VariantBasicType::Object as u8
20}
21
22struct ObjectHeaderWriter<const OFFSET_SIZE: u8, const ID_SIZE: u8>();
23
24impl<const OFFSET_SIZE: u8, const ID_SIZE: u8> ObjectHeaderWriter<OFFSET_SIZE, ID_SIZE> {
25    fn write(
26        dst: &mut Vec<u8>,
27        num_fields: usize,
28        field_ids: impl Iterator<Item = u32>,
29        offsets: impl Iterator<Item = usize>,
30        data_size: usize,
31    ) {
32        let is_large = num_fields > u8::MAX as usize;
33        // num_fields will consume 4 bytes when it is larger than u8::MAX
34        if is_large {
35            dst.push(object_header::<1, { ID_SIZE }, { OFFSET_SIZE }>());
36            append_packed_u32::<4>(dst, num_fields);
37        } else {
38            dst.push(object_header::<0, { ID_SIZE }, { OFFSET_SIZE }>());
39            append_packed_u32::<1>(dst, num_fields);
40        }
41
42        for id in field_ids {
43            append_packed_u32::<ID_SIZE>(dst, id as usize);
44        }
45
46        for off in offsets {
47            append_packed_u32::<OFFSET_SIZE>(dst, off);
48        }
49
50        append_packed_u32::<OFFSET_SIZE>(dst, data_size);
51    }
52}
53
54#[inline(always)]
55fn append_packed_u32<const SIZE: u8>(dest: &mut Vec<u8>, value: usize) {
56    dest.extend_from_slice(&value.to_le_bytes()[..SIZE as usize]);
57}
58
59/// A builder for creating [`Variant::Object`] values.
60///
61/// See the examples on [`VariantBuilder`] for usage.
62///
63/// [`VariantBuilder`]: crate::VariantBuilder
64#[derive(Debug)]
65pub struct ObjectBuilder<'a, S: BuilderSpecificState> {
66    parent_state: ParentState<'a, S>,
67    pub(crate) fields: IndexMap<u32, usize>, // (field_id, offset)
68    validate_unique_fields: bool,
69}
70
71impl<'a, S: BuilderSpecificState> ObjectBuilder<'a, S> {
72    /// Creates a new object builder, nested on top of the given parent state.
73    pub fn new(parent_state: ParentState<'a, S>, validate_unique_fields: bool) -> Self {
74        Self {
75            parent_state,
76            fields: IndexMap::new(),
77            validate_unique_fields,
78        }
79    }
80
81    /// Add a field with key and value to the object
82    ///
83    /// # See Also
84    /// - [`ObjectBuilder::try_insert`] for a fallible version.
85    /// - [`ObjectBuilder::with_field`] for a builder-style API.
86    ///
87    /// # Panics
88    ///
89    /// This method will panic if the variant contains duplicate field names in objects
90    /// when validation is enabled. For a fallible version, use [`ObjectBuilder::try_insert`]
91    pub fn insert<'m, 'd, T: Into<Variant<'m, 'd>>>(&mut self, key: &str, value: T) {
92        let (state, _) = self.parent_state(key).unwrap();
93        ValueBuilder::append_variant(state, value.into())
94    }
95
96    /// Add a field with key and value to the object
97    ///
98    /// # See Also
99    /// - [`ObjectBuilder::insert`] for an infallible version that panics
100    /// - [`ObjectBuilder::try_with_field`] for a builder-style API.
101    ///
102    /// # Note
103    /// Attempting to insert a duplicate field name produces an error if unique field
104    /// validation is enabled. Otherwise, the new value overwrites the previous field mapping
105    /// without erasing the old value, resulting in a larger variant
106    pub fn try_insert<'m, 'd, T: Into<Variant<'m, 'd>>>(
107        &mut self,
108        key: &str,
109        value: T,
110    ) -> Result<(), ArrowError> {
111        let (state, _) = self.parent_state(key)?;
112        ValueBuilder::try_append_variant(state, value.into())
113    }
114
115    /// Add a field with key and value to the object by copying raw bytes when possible.
116    ///
117    /// For objects and lists, this directly copies their underlying byte representation instead of
118    /// performing a logical copy, and without touching the metadata builder. For other variant
119    /// types, this falls back to the standard append behavior.
120    ///
121    /// The caller must ensure that the metadata dictionary is already built and correct for
122    /// any objects or lists being appended, but the value's new field name is handled normally.
123    ///
124    /// # Panics
125    ///
126    /// This method will panic if the variant contains duplicate field names in objects
127    /// when validation is enabled. For a fallible version, use [`ObjectBuilder::try_insert_bytes`]
128    pub fn insert_bytes<'m, 'd>(&mut self, key: &str, value: impl Into<Variant<'m, 'd>>) {
129        self.try_insert_bytes(key, value).unwrap()
130    }
131
132    /// Add a field with key and value to the object by copying raw bytes when possible.
133    ///
134    /// For objects and lists, this directly copies their underlying byte representation instead of
135    /// performing a logical copy, and without touching the metadata builder. For other variant
136    /// types, this falls back to the standard append behavior.
137    ///
138    /// The caller must ensure that the metadata dictionary is already built and correct for
139    /// any objects or lists being appended, but the value's new field name is handled normally.
140    ///
141    /// # Note
142    /// When inserting duplicate keys, the new value overwrites the previous mapping,
143    /// but the old value remains in the buffer, resulting in a larger variant
144    pub fn try_insert_bytes<'m, 'd>(
145        &mut self,
146        key: &str,
147        value: impl Into<Variant<'m, 'd>>,
148    ) -> Result<(), ArrowError> {
149        let (state, _) = self.parent_state(key)?;
150        ValueBuilder::append_variant_bytes(state, value.into());
151        Ok(())
152    }
153
154    /// Builder style API for adding a field with key and value to the object
155    ///
156    /// Same as [`ObjectBuilder::insert`], but returns `self` for chaining.
157    pub fn with_field<'m, 'd, T: Into<Variant<'m, 'd>>>(mut self, key: &str, value: T) -> Self {
158        self.insert(key, value);
159        self
160    }
161
162    /// Builder style API for adding a field with key and value to the object
163    ///
164    /// Same as [`ObjectBuilder::try_insert`], but returns `self` for chaining.
165    pub fn try_with_field<'m, 'd, T: Into<Variant<'m, 'd>>>(
166        mut self,
167        key: &str,
168        value: T,
169    ) -> Result<Self, ArrowError> {
170        self.try_insert(key, value)?;
171        Ok(self)
172    }
173
174    /// Enables validation for unique field keys when inserting into this object.
175    ///
176    /// When enabled, inserting a duplicate field key fails: the `try_*` methods
177    /// (e.g. [`ObjectBuilder::try_insert`]) return an error, and the others
178    /// (e.g. [`ObjectBuilder::insert`]) panic.
179    pub fn with_validate_unique_fields(mut self, validate_unique_fields: bool) -> Self {
180        self.validate_unique_fields = validate_unique_fields;
181        self
182    }
183
184    // Returns validate_unique_fields because we can no longer reference self once this method returns.
185    fn parent_state<'b>(
186        &'b mut self,
187        field_name: &str,
188    ) -> Result<(ParentState<'b, ObjectState<'b>>, bool), ArrowError> {
189        let validate_unique_fields = self.validate_unique_fields;
190        let state = ParentState::try_object(
191            self.parent_state.value_builder,
192            self.parent_state.metadata_builder,
193            &mut self.fields,
194            self.parent_state.saved_value_builder_offset,
195            field_name,
196            validate_unique_fields,
197        )?;
198        Ok((state, validate_unique_fields))
199    }
200
201    /// Returns an object builder that can be used to append a new (nested) object to this object.
202    ///
203    /// WARNING: The builder will have no effect unless/until [`ObjectBuilder::finish`] is called.
204    ///
205    /// # Panics
206    ///
207    /// Panics if the proposed key was a duplicate
208    pub fn new_object<'b>(&'b mut self, key: &'b str) -> ObjectBuilder<'b, ObjectState<'b>> {
209        self.try_new_object(key).unwrap()
210    }
211
212    /// Returns an object builder that can be used to append a new (nested) object to this object.
213    ///
214    /// Fails if the proposed key was a duplicate
215    ///
216    /// WARNING: The builder will have no effect unless/until [`ObjectBuilder::finish`] is called.
217    pub fn try_new_object<'b>(
218        &'b mut self,
219        key: &str,
220    ) -> Result<ObjectBuilder<'b, ObjectState<'b>>, ArrowError> {
221        let (parent_state, validate_unique_fields) = self.parent_state(key)?;
222        Ok(ObjectBuilder::new(parent_state, validate_unique_fields))
223    }
224
225    /// Returns a list builder that can be used to append a new (nested) list to this object.
226    ///
227    /// WARNING: The builder will have no effect unless/until [`ListBuilder::finish`] is called.
228    ///
229    /// # Panics
230    ///
231    /// Panics if the proposed key was a duplicate
232    pub fn new_list<'b>(&'b mut self, key: &str) -> ListBuilder<'b, ObjectState<'b>> {
233        self.try_new_list(key).unwrap()
234    }
235
236    /// Returns a list builder that can be used to append a new (nested) list to this object.
237    ///
238    /// Fails if the proposed key was a duplicate
239    ///
240    /// WARNING: The builder will have no effect unless/until [`ListBuilder::finish`] is called.
241    pub fn try_new_list<'b>(
242        &'b mut self,
243        key: &str,
244    ) -> Result<ListBuilder<'b, ObjectState<'b>>, ArrowError> {
245        let (parent_state, validate_unique_fields) = self.parent_state(key)?;
246        Ok(ListBuilder::new(parent_state, validate_unique_fields))
247    }
248
249    /// Finalizes this object and appends it to its parent, which otherwise remains unmodified.
250    pub fn finish(mut self) {
251        let metadata_builder = self.parent_state.metadata_builder();
252
253        self.fields.sort_by(|&field_a_id, _, &field_b_id, _| {
254            let field_a_name = metadata_builder.field_name(field_a_id as usize);
255            let field_b_name = metadata_builder.field_name(field_b_id as usize);
256            field_a_name.cmp(field_b_name)
257        });
258
259        let max_id = self.fields.iter().map(|(i, _)| *i).max().unwrap_or(0);
260        let id_size = int_size(max_id as usize);
261
262        let starting_offset = self.parent_state.saved_value_builder_offset;
263        let value_builder = self.parent_state.value_builder();
264        let current_offset = value_builder.offset();
265        // Current object starts from `object_start_offset`
266        let data_size = current_offset - starting_offset;
267        let offset_size = int_size(data_size);
268
269        let num_fields = self.fields.len();
270        let is_large = num_fields > u8::MAX as usize;
271
272        let header_size = 1 + // header byte
273            (if is_large { 4 } else { 1 }) + // num_fields
274            (num_fields * id_size as usize) + // field IDs
275            ((num_fields + 1) * offset_size as usize); // field offsets + data_size
276
277        let mut bytes_to_splice = Vec::with_capacity(header_size);
278
279        macro_rules! write_header {
280            ($offset_size:expr, $id_size:expr) => {
281                ObjectHeaderWriter::<{ $offset_size as u8 }, { $id_size as u8 }>::write(
282                    &mut bytes_to_splice,
283                    num_fields,
284                    self.fields.keys().copied(),
285                    self.fields.values().copied(),
286                    data_size,
287                )
288            };
289        }
290
291        use crate::decoder::OffsetSizeBytes::*;
292        match (offset_size, id_size) {
293            (One, One) => write_header!(One, One),
294            (One, Two) => write_header!(One, Two),
295            (One, Three) => write_header!(One, Three),
296            (One, Four) => write_header!(One, Four),
297            (Two, One) => write_header!(Two, One),
298            (Two, Two) => write_header!(Two, Two),
299            (Two, Three) => write_header!(Two, Three),
300            (Two, Four) => write_header!(Two, Four),
301            (Three, One) => write_header!(Three, One),
302            (Three, Two) => write_header!(Three, Two),
303            (Three, Three) => write_header!(Three, Three),
304            (Three, Four) => write_header!(Three, Four),
305            (Four, One) => write_header!(Four, One),
306            (Four, Two) => write_header!(Four, Two),
307            (Four, Three) => write_header!(Four, Three),
308            (Four, Four) => write_header!(Four, Four),
309        }
310
311        // Shift existing data to make room for the header
312        value_builder
313            .inner_mut()
314            .splice(starting_offset..starting_offset, bytes_to_splice);
315
316        self.parent_state.finish();
317    }
318}
319
320impl<'m, 'v, S, K, V> Extend<(K, V)> for ObjectBuilder<'_, S>
321where
322    S: BuilderSpecificState,
323    K: AsRef<str>,
324    V: Into<Variant<'m, 'v>>,
325{
326    fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T) {
327        for (key, value) in iter {
328            self.insert(key.as_ref(), value);
329        }
330    }
331}
332
333/// Internal state for object building
334#[derive(Debug)]
335pub struct ObjectState<'a> {
336    fields: &'a mut IndexMap<u32, usize>,
337    saved_fields_size: usize,
338    replaced_field: Option<(u32, usize)>,
339}
340
341// `ObjectBuilder::finish()` eagerly updates the field offsets, which we should rollback on failure.
342impl BuilderSpecificState for ObjectState<'_> {
343    fn rollback(&mut self) {
344        self.fields.truncate(self.saved_fields_size);
345        if let Some((field_id, offset)) = self.replaced_field {
346            self.fields.insert(field_id, offset);
347        }
348    }
349}
350
351impl<'a> ParentState<'a, ObjectState<'a>> {
352    /// Creates a new instance suitable for an [`ObjectBuilder`]. The value and metadata builder state
353    /// is checkpointed and will roll back on drop, unless [`Self::finish`] is called. The new
354    /// field's name and offset are also captured eagerly and will also roll back if not finished.
355    ///
356    /// The call fails if the field name is invalid (e.g. because it duplicates an existing field).
357    pub fn try_object(
358        value_builder: &'a mut ValueBuilder,
359        metadata_builder: &'a mut dyn MetadataBuilder,
360        fields: &'a mut IndexMap<u32, usize>,
361        saved_parent_value_builder_offset: usize,
362        field_name: &str,
363        validate_unique_fields: bool,
364    ) -> Result<Self, ArrowError> {
365        // The saved_parent_buffer_offset is the buffer size as of when the parent builder was
366        // constructed. The saved_buffer_offset is the buffer size as of now (when a child builder
367        // is created). The variant field_offset entry for this field is their difference.
368        let saved_value_builder_offset = value_builder.offset();
369        let saved_fields_size = fields.len();
370        let saved_metadata_builder_dict_size = metadata_builder.num_field_names();
371        let field_id = metadata_builder.try_upsert_field_name(field_name)?;
372        let field_start = saved_value_builder_offset - saved_parent_value_builder_offset;
373        let replaced_field = if validate_unique_fields {
374            match fields.entry(field_id) {
375                Entry::Occupied(_) => {
376                    return Err(ArrowError::InvalidArgumentError(format!(
377                        "Duplicate field name: {field_name}"
378                    )));
379                }
380                Entry::Vacant(field) => {
381                    field.insert(field_start);
382                    None
383                }
384            }
385        } else {
386            fields
387                .insert(field_id, field_start)
388                .map(|offset| (field_id, offset))
389        };
390
391        let builder_state = ObjectState {
392            fields,
393            saved_fields_size,
394            replaced_field,
395        };
396        Ok(Self {
397            saved_metadata_builder_dict_size,
398            saved_value_builder_offset,
399            value_builder,
400            metadata_builder,
401            builder_state,
402            finished: false,
403        })
404    }
405}
406
407/// A [`VariantBuilderExt`] that inserts a new field into a variant object.
408pub struct ObjectFieldBuilder<'o, 'v, 's, S: BuilderSpecificState> {
409    key: &'s str,
410    builder: &'o mut ObjectBuilder<'v, S>,
411}
412
413impl<'o, 'v, 's, S: BuilderSpecificState> ObjectFieldBuilder<'o, 'v, 's, S> {
414    pub fn new(key: &'s str, builder: &'o mut ObjectBuilder<'v, S>) -> Self {
415        Self { key, builder }
416    }
417}
418
419impl<S: BuilderSpecificState> VariantBuilderExt for ObjectFieldBuilder<'_, '_, '_, S> {
420    type State<'a>
421        = ObjectState<'a>
422    where
423        Self: 'a;
424
425    /// A NULL object field is interpreted as missing, so nothing gets inserted at all.
426    fn append_null(&mut self) {}
427    fn append_value<'m, 'v>(&mut self, value: impl Into<Variant<'m, 'v>>) {
428        self.builder.insert(self.key, value);
429    }
430
431    fn try_new_list(&mut self) -> Result<ListBuilder<'_, Self::State<'_>>, ArrowError> {
432        self.builder.try_new_list(self.key)
433    }
434
435    fn try_new_object(&mut self) -> Result<ObjectBuilder<'_, Self::State<'_>>, ArrowError> {
436        self.builder.try_new_object(self.key)
437    }
438}
439
440#[cfg(test)]
441mod tests {
442    use crate::{
443        ParentState, ValueBuilder, Variant, VariantBuilder, VariantMetadata,
444        WritableMetadataBuilder,
445        builder::{metadata::ReadOnlyMetadataBuilder, object::ObjectBuilder},
446        decoder::VariantBasicType,
447    };
448
449    #[test]
450    fn test_object() {
451        let mut builder = VariantBuilder::new();
452
453        builder
454            .new_object()
455            .with_field("name", "John")
456            .with_field("age", 42i8)
457            .finish();
458
459        let (metadata, value) = builder.finish();
460        assert!(!metadata.is_empty());
461        assert!(!value.is_empty());
462    }
463
464    #[test]
465    fn test_object_field_ordering() {
466        let mut builder = VariantBuilder::new();
467
468        builder
469            .new_object()
470            .with_field("zebra", "stripes")
471            .with_field("apple", "red")
472            .with_field("banana", "yellow")
473            .finish();
474
475        let (_, value) = builder.finish();
476
477        let header = value[0];
478        assert_eq!(header & 0x03, VariantBasicType::Object as u8);
479
480        let field_count = value[1] as usize;
481        assert_eq!(field_count, 3);
482
483        // Get field IDs from the object header
484        let field_ids: Vec<u8> = value[2..5].to_vec();
485
486        // apple(1), banana(2), zebra(0)
487        assert_eq!(field_ids, vec![1, 2, 0]);
488    }
489
490    #[test]
491    fn test_duplicate_fields_in_object() {
492        let mut builder = VariantBuilder::new();
493        builder
494            .new_object()
495            .with_field("name", "Ron Artest")
496            .with_field("name", "Metta World Peace") // Duplicate field
497            .finish();
498
499        let (metadata, value) = builder.finish();
500        let variant = Variant::try_new(&metadata, &value).unwrap();
501
502        let obj = variant.as_object().unwrap();
503        assert_eq!(obj.len(), 1);
504        assert_eq!(obj.field(0).unwrap(), Variant::from("Metta World Peace"));
505
506        assert_eq!(
507            vec![("name", Variant::from("Metta World Peace"))],
508            obj.iter().collect::<Vec<_>>()
509        );
510    }
511
512    #[test]
513    fn test_read_only_metadata_builder() {
514        // First create some metadata with a few field names
515        let mut default_builder = WritableMetadataBuilder::default();
516        default_builder.upsert_field_name("name");
517        default_builder.upsert_field_name("age");
518        default_builder.upsert_field_name("active");
519        default_builder.finish();
520        let metadata_bytes = default_builder.into_inner();
521
522        // Use the metadata to build new variant values
523        let metadata = VariantMetadata::try_new(&metadata_bytes).unwrap();
524        let mut metadata_builder = ReadOnlyMetadataBuilder::new(&metadata);
525        let mut value_builder = ValueBuilder::new();
526
527        {
528            let state = ParentState::variant(&mut value_builder, &mut metadata_builder);
529            let mut obj = ObjectBuilder::new(state, false);
530
531            // These should succeed because the fields exist in the metadata
532            obj.insert("name", "Alice");
533            obj.insert("age", 30i8);
534            obj.insert("active", true);
535            obj.finish();
536        }
537
538        let value = value_builder.into_inner();
539
540        // Verify the variant was built correctly
541        let variant = Variant::try_new(&metadata_bytes, &value).unwrap();
542        let obj = variant.as_object().unwrap();
543        assert_eq!(obj.get("name"), Some(Variant::from("Alice")));
544        assert_eq!(obj.get("age"), Some(Variant::Int8(30)));
545        assert_eq!(obj.get("active"), Some(Variant::from(true)));
546    }
547
548    /// A dictionary that is not marked sorted may legally hold the same string at more than one
549    /// field id. A field name must still resolve to a single id, or an object builder sharing that
550    /// dictionary would emit two fields with the same name.
551    ///
552    /// Metadata dictionary `["a", "a"]`, unsorted:
553    const DUPLICATE_ENTRY_METADATA: &[u8] = &[
554        0b0000_0001, // header: offset_size_minus_one=0, sorted=0, version=1
555        2,           // dictionary_size
556        0x00,
557        0x01,
558        0x02,
559        b'a',
560        b'a',
561    ];
562
563    #[test]
564    fn test_read_only_metadata_builder_duplicate_dictionary_entries_are_detected() {
565        let metadata = VariantMetadata::try_new(DUPLICATE_ENTRY_METADATA).unwrap();
566        assert!(!metadata.is_sorted());
567
568        let mut metadata_builder = ReadOnlyMetadataBuilder::new(&metadata);
569        let mut value_builder = ValueBuilder::new();
570        let state = ParentState::variant(&mut value_builder, &mut metadata_builder);
571        let mut obj = ObjectBuilder::new(state, true);
572
573        // Both dictionary entries name "a", so inserting both must be reported as a duplicate
574        // field name rather than producing an object with two fields named "a".
575        obj.insert(metadata.get(0).unwrap(), 1i8);
576        let err = obj
577            .try_insert(metadata.get(1).unwrap(), 2i8)
578            .expect_err("duplicate field name should be rejected");
579        assert!(
580            err.to_string().contains("Duplicate field name"),
581            "unexpected error: {err}"
582        );
583    }
584
585    #[test]
586    fn test_read_only_metadata_builder_duplicate_dictionary_entries_build_valid_object() {
587        let metadata = VariantMetadata::try_new(DUPLICATE_ENTRY_METADATA).unwrap();
588
589        let mut metadata_builder = ReadOnlyMetadataBuilder::new(&metadata);
590        let mut value_builder = ValueBuilder::new();
591        {
592            let state = ParentState::variant(&mut value_builder, &mut metadata_builder);
593            let mut obj = ObjectBuilder::new(state, false);
594
595            // A name borrowed from the dictionary and an owned copy of that same name must resolve
596            // to the same field id, so that the last write wins instead of both being emitted.
597            obj.insert(metadata.get(1).unwrap(), 1i8);
598            let owned = String::from("a");
599            obj.insert(owned.as_str(), 2i8);
600            obj.finish();
601        }
602
603        let value = value_builder.into_inner();
604        let variant = Variant::try_new(DUPLICATE_ENTRY_METADATA, &value).unwrap();
605        let obj = variant.as_object().unwrap();
606        assert_eq!(obj.len(), 1);
607        assert_eq!(obj.get("a"), Some(Variant::Int8(2)));
608    }
609
610    // matthew
611    #[test]
612    fn test_append_object() {
613        let (m1, v1) = make_object();
614        let variant = Variant::new(&m1, &v1);
615
616        let mut builder = VariantBuilder::new().with_metadata(VariantMetadata::new(&m1));
617
618        builder.append_value(variant.clone());
619
620        let (metadata, value) = builder.finish();
621        assert_eq!(variant, Variant::new(&metadata, &value));
622    }
623
624    /// make an object variant with field names in reverse lexicographical order
625    fn make_object() -> (Vec<u8>, Vec<u8>) {
626        let mut builder = VariantBuilder::new();
627
628        let mut obj = builder.new_object();
629
630        obj.insert("b", true);
631        obj.insert("a", false);
632        obj.finish();
633        builder.finish()
634    }
635
636    #[test]
637    fn test_append_nested_object() {
638        let (m1, v1) = make_nested_object();
639        let variant = Variant::new(&m1, &v1);
640
641        // because we can guarantee metadata is validated through the builder
642        let mut builder = VariantBuilder::new().with_metadata(VariantMetadata::new(&m1));
643        builder.append_value(variant.clone());
644
645        let (metadata, value) = builder.finish();
646        let result_variant = Variant::new(&metadata, &value);
647
648        assert_eq!(variant, result_variant);
649    }
650
651    /// make a nested object variant
652    fn make_nested_object() -> (Vec<u8>, Vec<u8>) {
653        let mut builder = VariantBuilder::new();
654
655        {
656            let mut outer_obj = builder.new_object();
657
658            {
659                let mut inner_obj = outer_obj.new_object("b");
660                inner_obj.insert("a", "inner_value");
661                inner_obj.finish();
662            }
663
664            outer_obj.finish();
665        }
666
667        builder.finish()
668    }
669
670    #[test]
671    fn test_nested_object() {
672        /*
673        {
674            "c": {
675                "b": "a"
676            }
677        }
678
679        */
680
681        let mut builder = VariantBuilder::new();
682        {
683            let mut outer_object_builder = builder.new_object();
684            {
685                let mut inner_object_builder = outer_object_builder.new_object("c");
686                inner_object_builder.insert("b", "a");
687                inner_object_builder.finish();
688            }
689
690            outer_object_builder.finish();
691        }
692
693        let (metadata, value) = builder.finish();
694        let variant = Variant::try_new(&metadata, &value).unwrap();
695        let outer_object = variant.as_object().unwrap();
696
697        assert_eq!(outer_object.len(), 1);
698        assert_eq!(outer_object.field_name(0).unwrap(), "c");
699
700        let inner_object_variant = outer_object.field(0).unwrap();
701        let inner_object = inner_object_variant.as_object().unwrap();
702
703        assert_eq!(inner_object.len(), 1);
704        assert_eq!(inner_object.field_name(0).unwrap(), "b");
705        assert_eq!(inner_object.field(0).unwrap(), Variant::from("a"));
706    }
707
708    #[test]
709    fn test_nested_object_with_duplicate_field_names_per_object() {
710        /*
711        {
712            "c": {
713                "b": false,
714                "c": "a"
715            },
716            "b": false,
717        }
718
719        */
720
721        let mut builder = VariantBuilder::new();
722        {
723            let mut outer_object_builder = builder.new_object();
724            {
725                let mut inner_object_builder = outer_object_builder.new_object("c");
726                inner_object_builder.insert("b", false);
727                inner_object_builder.insert("c", "a");
728
729                inner_object_builder.finish();
730            }
731
732            outer_object_builder.insert("b", false);
733            outer_object_builder.finish();
734        }
735
736        let (metadata, value) = builder.finish();
737        let variant = Variant::try_new(&metadata, &value).unwrap();
738        let outer_object = variant.as_object().unwrap();
739
740        assert_eq!(outer_object.len(), 2);
741        assert_eq!(outer_object.field_name(0).unwrap(), "b");
742
743        let inner_object_variant = outer_object.field(1).unwrap();
744        let inner_object = inner_object_variant.as_object().unwrap();
745
746        assert_eq!(inner_object.len(), 2);
747        assert_eq!(inner_object.field_name(0).unwrap(), "b");
748        assert_eq!(inner_object.field(0).unwrap(), Variant::from(false));
749        assert_eq!(inner_object.field_name(1).unwrap(), "c");
750        assert_eq!(inner_object.field(1).unwrap(), Variant::from("a"));
751    }
752
753    #[test]
754    fn test_nested_object_with_heterogeneous_fields() {
755        /*
756        {
757            "a": false,
758            "c": {
759                "b": "a",
760                "c": {
761                   "aa": "bb",
762                },
763                "d": {
764                    "cc": "dd"
765                }
766            },
767            "b": true,
768            "d": {
769               "e": 1,
770               "f": [1, true],
771               "g": ["tree", false],
772            }
773        }
774        */
775
776        let mut builder = VariantBuilder::new();
777        {
778            let mut outer_object_builder = builder.new_object();
779
780            outer_object_builder.insert("a", false);
781
782            {
783                let mut inner_object_builder = outer_object_builder.new_object("c");
784                inner_object_builder.insert("b", "a");
785
786                {
787                    let mut inner_inner_object_builder = inner_object_builder.new_object("c");
788                    inner_inner_object_builder.insert("aa", "bb");
789                    inner_inner_object_builder.finish();
790                }
791
792                {
793                    let mut inner_inner_object_builder = inner_object_builder.new_object("d");
794                    inner_inner_object_builder.insert("cc", "dd");
795                    inner_inner_object_builder.finish();
796                }
797                inner_object_builder.finish();
798            }
799
800            outer_object_builder.insert("b", true);
801
802            {
803                let mut inner_object_builder = outer_object_builder.new_object("d");
804                inner_object_builder.insert("e", 1);
805                {
806                    let mut inner_list_builder = inner_object_builder.new_list("f");
807                    inner_list_builder.append_value(1);
808                    inner_list_builder.append_value(true);
809
810                    inner_list_builder.finish();
811                }
812
813                {
814                    let mut inner_list_builder = inner_object_builder.new_list("g");
815                    inner_list_builder.append_value("tree");
816                    inner_list_builder.append_value(false);
817
818                    inner_list_builder.finish();
819                }
820
821                inner_object_builder.finish();
822            }
823
824            outer_object_builder.finish();
825        }
826
827        let (metadata, value) = builder.finish();
828
829        // note, object fields are now sorted lexicographically by field name
830        /*
831         {
832            "a": false,
833            "b": true,
834            "c": {
835                "b": "a",
836                "c": {
837                   "aa": "bb",
838                },
839                "d": {
840                    "cc": "dd"
841                }
842            },
843            "d": {
844               "e": 1,
845               "f": [1, true],
846               "g": ["tree", false],
847            }
848        }
849        */
850
851        let variant = Variant::try_new(&metadata, &value).unwrap();
852        let outer_object = variant.as_object().unwrap();
853
854        assert_eq!(outer_object.len(), 4);
855
856        assert_eq!(outer_object.field_name(0).unwrap(), "a");
857        assert_eq!(outer_object.field(0).unwrap(), Variant::from(false));
858
859        assert_eq!(outer_object.field_name(2).unwrap(), "c");
860
861        let inner_object_variant = outer_object.field(2).unwrap();
862        let inner_object = inner_object_variant.as_object().unwrap();
863
864        assert_eq!(inner_object.len(), 3);
865        assert_eq!(inner_object.field_name(0).unwrap(), "b");
866        assert_eq!(inner_object.field(0).unwrap(), Variant::from("a"));
867
868        let inner_iner_object_variant_c = inner_object.field(1).unwrap();
869        let inner_inner_object_c = inner_iner_object_variant_c.as_object().unwrap();
870        assert_eq!(inner_inner_object_c.len(), 1);
871        assert_eq!(inner_inner_object_c.field_name(0).unwrap(), "aa");
872        assert_eq!(inner_inner_object_c.field(0).unwrap(), Variant::from("bb"));
873
874        let inner_iner_object_variant_d = inner_object.field(2).unwrap();
875        let inner_inner_object_d = inner_iner_object_variant_d.as_object().unwrap();
876        assert_eq!(inner_inner_object_d.len(), 1);
877        assert_eq!(inner_inner_object_d.field_name(0).unwrap(), "cc");
878        assert_eq!(inner_inner_object_d.field(0).unwrap(), Variant::from("dd"));
879
880        assert_eq!(outer_object.field_name(1).unwrap(), "b");
881        assert_eq!(outer_object.field(1).unwrap(), Variant::from(true));
882
883        let out_object_variant_d = outer_object.field(3).unwrap();
884        let out_object_d = out_object_variant_d.as_object().unwrap();
885        assert_eq!(out_object_d.len(), 3);
886        assert_eq!("e", out_object_d.field_name(0).unwrap());
887        assert_eq!(Variant::from(1), out_object_d.field(0).unwrap());
888        assert_eq!("f", out_object_d.field_name(1).unwrap());
889
890        let first_inner_list_variant_f = out_object_d.field(1).unwrap();
891        let first_inner_list_f = first_inner_list_variant_f.as_list().unwrap();
892        assert_eq!(2, first_inner_list_f.len());
893        assert_eq!(Variant::from(1), first_inner_list_f.get(0).unwrap());
894        assert_eq!(Variant::from(true), first_inner_list_f.get(1).unwrap());
895
896        let second_inner_list_variant_g = out_object_d.field(2).unwrap();
897        let second_inner_list_g = second_inner_list_variant_g.as_list().unwrap();
898        assert_eq!(2, second_inner_list_g.len());
899        assert_eq!(Variant::from("tree"), second_inner_list_g.get(0).unwrap());
900        assert_eq!(Variant::from(false), second_inner_list_g.get(1).unwrap());
901    }
902
903    #[test]
904    fn test_object_without_unique_field_validation() {
905        let mut builder = VariantBuilder::new();
906
907        // Root object with duplicates
908        let mut obj = builder.new_object();
909        obj.insert("a", 1);
910        obj.insert("a", 2);
911        obj.finish();
912
913        // Deeply nested list structure with duplicates
914        let mut builder = VariantBuilder::new();
915        let mut outer_list = builder.new_list();
916        let mut inner_list = outer_list.new_list();
917        let mut nested_obj = inner_list.new_object();
918        nested_obj.insert("x", 1);
919        nested_obj.insert("x", 2);
920        nested_obj.new_list("x").with_value(3).finish();
921        nested_obj.new_object("x").with_field("y", 4).finish();
922        nested_obj.finish();
923        inner_list.finish();
924        outer_list.finish();
925
926        // Verify the nested object is built correctly -- the nested object "x" should have "won"
927        let (metadata, value) = builder.finish();
928        let variant = Variant::try_new(&metadata, &value).unwrap();
929        let outer_element = variant.get_list_element(0).unwrap();
930        let inner_element = outer_element.get_list_element(0).unwrap();
931        let outer_field = inner_element.get_object_field("x").unwrap();
932        let inner_field = outer_field.get_object_field("y").unwrap();
933        assert_eq!(inner_field, Variant::from(4));
934    }
935
936    #[test]
937    fn test_object_with_unique_field_validation() {
938        let mut builder = VariantBuilder::new().with_validate_unique_fields(true);
939
940        // Root-level object with duplicates
941        let result = builder
942            .new_object()
943            .with_field("a", 1)
944            .with_field("b", 2)
945            .try_with_field("a", 3);
946        assert_eq!(
947            result.unwrap_err().to_string(),
948            "Invalid argument error: Duplicate field name: a"
949        );
950
951        // Deeply nested list -> list -> object with duplicate
952        let mut outer_list = builder.new_list();
953        let mut inner_list = outer_list.new_list();
954        let mut object = inner_list.new_object().with_field("x", 1);
955        let nested_result = object.try_insert("x", 2);
956        assert_eq!(
957            nested_result.unwrap_err().to_string(),
958            "Invalid argument error: Duplicate field name: x"
959        );
960        let nested_result = object.try_new_list("x");
961        assert_eq!(
962            nested_result.unwrap_err().to_string(),
963            "Invalid argument error: Duplicate field name: x"
964        );
965
966        let nested_result = object.try_new_object("x");
967        assert_eq!(
968            nested_result.unwrap_err().to_string(),
969            "Invalid argument error: Duplicate field name: x"
970        );
971
972        drop(object);
973        inner_list.finish();
974        outer_list.finish();
975
976        // Valid object should succeed (fresh builder — one top-level value per VariantBuilder)
977        let mut builder = VariantBuilder::new().with_validate_unique_fields(true);
978        let mut list = builder.new_list();
979        let mut valid_obj = list.new_object();
980        valid_obj.insert("m", 1);
981        valid_obj.insert("n", 2);
982
983        valid_obj.finish();
984        list.finish();
985    }
986
987    #[test]
988    fn test_object_can_continue_after_duplicate_field_error() {
989        let mut builder = VariantBuilder::new().with_validate_unique_fields(true);
990        let mut object = builder.new_object();
991        object.try_insert("a", 1).unwrap();
992
993        let error = object.try_insert("a", 2).unwrap_err();
994        assert_eq!(
995            error.to_string(),
996            "Invalid argument error: Duplicate field name: a"
997        );
998
999        object.try_insert("b", 3).unwrap();
1000        object.finish();
1001        let (metadata, value) = builder.finish();
1002        let variant = Variant::try_new(&metadata, &value).unwrap();
1003        assert_eq!(variant.get_object_field("a"), Some(Variant::Int32(1)));
1004        assert_eq!(variant.get_object_field("b"), Some(Variant::Int32(3)));
1005    }
1006
1007    #[test]
1008    fn test_failed_overwrite_preserves_previous_field() {
1009        let mut source = VariantBuilder::new();
1010        source.new_list().with_value(1i8).finish();
1011        let (metadata, mut value) = source.finish();
1012        let child_header = value.len() - 2;
1013        value[child_header] = 0xff;
1014        let invalid = Variant::new(&metadata, &value);
1015
1016        let mut builder = VariantBuilder::new();
1017        let mut object = builder.new_object();
1018        object.try_insert("a", 1i32).unwrap();
1019        assert!(object.try_insert("a", invalid).is_err());
1020        object.try_insert("b", 2i32).unwrap();
1021        object.finish();
1022
1023        let (metadata, value) = builder.finish();
1024        let variant = Variant::try_new(&metadata, &value).unwrap();
1025        assert_eq!(variant.get_object_field("a"), Some(Variant::Int32(1)));
1026        assert_eq!(variant.get_object_field("b"), Some(Variant::Int32(2)));
1027    }
1028}