Skip to main content

parquet_variant/
builder.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::decoder::{OffsetSizeBytes, VariantBasicType, VariantPrimitiveType};
6use crate::{
7    ShortString, Variant, VariantDecimal4, VariantDecimal8, VariantDecimal16, VariantList,
8    VariantMetadata, VariantObject,
9};
10use arrow_schema::ArrowError;
11use chrono::Timelike;
12use uuid::Uuid;
13
14mod list;
15mod metadata;
16mod object;
17
18pub use list::*;
19pub use metadata::*;
20pub use object::*;
21
22pub(crate) const BASIC_TYPE_BITS: u8 = 2;
23pub(crate) const UNIX_EPOCH_DATE: chrono::NaiveDate =
24    chrono::NaiveDate::from_ymd_opt(1970, 1, 1).unwrap();
25
26fn primitive_header(primitive_type: VariantPrimitiveType) -> u8 {
27    ((primitive_type as u8) << 2) | VariantBasicType::Primitive as u8
28}
29
30fn short_string_header(len: usize) -> u8 {
31    ((len as u8) << 2) | VariantBasicType::ShortString as u8
32}
33
34pub(crate) fn int_size(v: usize) -> OffsetSizeBytes {
35    match v {
36        0..=0xFF => OffsetSizeBytes::One,
37        0x100..=0xFFFF => OffsetSizeBytes::Two,
38        0x10000..=0xFFFFFF => OffsetSizeBytes::Three,
39        _ => OffsetSizeBytes::Four,
40    }
41}
42
43const ONE_TOP_LEVEL_VALUE_MSG: &str =
44    "VariantBuilder already contains a top-level variant value; only one is allowed";
45const EMPTY_BUILDER_MSG: &str =
46    "VariantBuilder is empty; append a top-level value before calling finish()";
47
48// Error/panic construction is kept out-of-line and cold so the per-call guards on the
49// builder hot paths stay small enough to inline as a single predictable branch.
50#[cold]
51#[inline(never)]
52fn top_level_value_panic() -> ! {
53    panic!("{ONE_TOP_LEVEL_VALUE_MSG}");
54}
55
56#[cold]
57#[inline(never)]
58fn top_level_value_error() -> ArrowError {
59    ArrowError::InvalidArgumentError(ONE_TOP_LEVEL_VALUE_MSG.into())
60}
61
62#[cold]
63#[inline(never)]
64fn empty_builder_error() -> ArrowError {
65    ArrowError::InvalidArgumentError(EMPTY_BUILDER_MSG.into())
66}
67
68/// Wrapper around a `Vec<u8>` that provides methods for appending
69/// primitive values, variant types, and metadata.
70///
71/// This is used internally by the builders to construct the
72/// the `value` field for [`Variant`] values.
73///
74/// You can reuse an existing `Vec<u8>` by using the `from` impl
75#[derive(Debug, Default)]
76pub struct ValueBuilder(Vec<u8>);
77
78impl ValueBuilder {
79    /// Construct a ValueBuffer that will write to a new underlying `Vec`
80    pub fn new() -> Self {
81        Default::default()
82    }
83}
84
85/// Macro to generate the match statement for each append_variant, try_append_variant, and
86/// append_variant_bytes -- they each have slightly different handling for object and list handling.
87macro_rules! variant_append_value {
88    ($builder:expr, $value:expr, $object_pat:pat => $object_arm:expr, $list_pat:pat => $list_arm:expr) => {
89        match $value {
90            Variant::Null => $builder.append_null(),
91            Variant::BooleanTrue => $builder.append_bool(true),
92            Variant::BooleanFalse => $builder.append_bool(false),
93            Variant::Int8(v) => $builder.append_int8(v),
94            Variant::Int16(v) => $builder.append_int16(v),
95            Variant::Int32(v) => $builder.append_int32(v),
96            Variant::Int64(v) => $builder.append_int64(v),
97            Variant::Date(v) => $builder.append_date(v),
98            Variant::Time(v) => $builder.append_time_micros(v),
99            Variant::TimestampMicros(v) => $builder.append_timestamp_micros(v),
100            Variant::TimestampNtzMicros(v) => $builder.append_timestamp_ntz_micros(v),
101            Variant::TimestampNanos(v) => $builder.append_timestamp_nanos(v),
102            Variant::TimestampNtzNanos(v) => $builder.append_timestamp_ntz_nanos(v),
103            Variant::Decimal4(decimal4) => $builder.append_decimal4(decimal4),
104            Variant::Decimal8(decimal8) => $builder.append_decimal8(decimal8),
105            Variant::Decimal16(decimal16) => $builder.append_decimal16(decimal16),
106            Variant::Float(v) => $builder.append_float(v),
107            Variant::Double(v) => $builder.append_double(v),
108            Variant::Binary(v) => $builder.append_binary(v),
109            Variant::String(s) => $builder.append_string(s),
110            Variant::ShortString(s) => $builder.append_short_string(s),
111            Variant::Uuid(v) => $builder.append_uuid(v),
112            $object_pat => $object_arm,
113            $list_pat => $list_arm,
114        }
115    };
116}
117
118impl ValueBuilder {
119    fn append_u8(&mut self, term: u8) {
120        self.0.push(term);
121    }
122
123    fn append_slice(&mut self, other: &[u8]) {
124        self.0.extend_from_slice(other);
125    }
126
127    fn append_primitive_header(&mut self, primitive_type: VariantPrimitiveType) {
128        self.0.push(primitive_header(primitive_type));
129    }
130
131    /// Returns the underlying buffer, consuming self
132    pub fn into_inner(self) -> Vec<u8> {
133        self.0
134    }
135
136    pub(crate) fn inner_mut(&mut self) -> &mut Vec<u8> {
137        &mut self.0
138    }
139
140    // Variant types below
141
142    fn append_null(&mut self) {
143        self.append_primitive_header(VariantPrimitiveType::Null);
144    }
145
146    fn append_bool(&mut self, value: bool) {
147        let primitive_type = if value {
148            VariantPrimitiveType::BooleanTrue
149        } else {
150            VariantPrimitiveType::BooleanFalse
151        };
152        self.append_primitive_header(primitive_type);
153    }
154
155    fn append_int8(&mut self, value: i8) {
156        self.append_primitive_header(VariantPrimitiveType::Int8);
157        self.append_u8(value as u8);
158    }
159
160    fn append_int16(&mut self, value: i16) {
161        self.append_primitive_header(VariantPrimitiveType::Int16);
162        self.append_slice(&value.to_le_bytes());
163    }
164
165    fn append_int32(&mut self, value: i32) {
166        self.append_primitive_header(VariantPrimitiveType::Int32);
167        self.append_slice(&value.to_le_bytes());
168    }
169
170    fn append_int64(&mut self, value: i64) {
171        self.append_primitive_header(VariantPrimitiveType::Int64);
172        self.append_slice(&value.to_le_bytes());
173    }
174
175    fn append_float(&mut self, value: f32) {
176        self.append_primitive_header(VariantPrimitiveType::Float);
177        self.append_slice(&value.to_le_bytes());
178    }
179
180    fn append_double(&mut self, value: f64) {
181        self.append_primitive_header(VariantPrimitiveType::Double);
182        self.append_slice(&value.to_le_bytes());
183    }
184
185    fn append_date(&mut self, value: chrono::NaiveDate) {
186        self.append_primitive_header(VariantPrimitiveType::Date);
187        let days_since_epoch = value.signed_duration_since(UNIX_EPOCH_DATE).num_days() as i32;
188        self.append_slice(&days_since_epoch.to_le_bytes());
189    }
190
191    fn append_timestamp_micros(&mut self, value: chrono::DateTime<chrono::Utc>) {
192        self.append_primitive_header(VariantPrimitiveType::TimestampMicros);
193        let micros = value.timestamp_micros();
194        self.append_slice(&micros.to_le_bytes());
195    }
196
197    fn append_timestamp_ntz_micros(&mut self, value: chrono::NaiveDateTime) {
198        self.append_primitive_header(VariantPrimitiveType::TimestampNtzMicros);
199        let micros = value.and_utc().timestamp_micros();
200        self.append_slice(&micros.to_le_bytes());
201    }
202
203    fn append_time_micros(&mut self, value: chrono::NaiveTime) {
204        self.append_primitive_header(VariantPrimitiveType::Time);
205        let micros_from_midnight = value.num_seconds_from_midnight() as u64 * 1_000_000
206            + value.nanosecond() as u64 / 1_000;
207        self.append_slice(&micros_from_midnight.to_le_bytes());
208    }
209
210    fn append_timestamp_nanos(&mut self, value: chrono::DateTime<chrono::Utc>) {
211        self.append_primitive_header(VariantPrimitiveType::TimestampNanos);
212        let nanos = value.timestamp_nanos_opt().unwrap();
213        self.append_slice(&nanos.to_le_bytes());
214    }
215
216    fn append_timestamp_ntz_nanos(&mut self, value: chrono::NaiveDateTime) {
217        self.append_primitive_header(VariantPrimitiveType::TimestampNtzNanos);
218        let nanos = value.and_utc().timestamp_nanos_opt().unwrap();
219        self.append_slice(&nanos.to_le_bytes());
220    }
221
222    fn append_uuid(&mut self, value: Uuid) {
223        self.append_primitive_header(VariantPrimitiveType::Uuid);
224        self.append_slice(&value.into_bytes());
225    }
226
227    fn append_decimal4(&mut self, decimal4: VariantDecimal4) {
228        self.append_primitive_header(VariantPrimitiveType::Decimal4);
229        self.append_u8(decimal4.scale());
230        self.append_slice(&decimal4.integer().to_le_bytes());
231    }
232
233    fn append_decimal8(&mut self, decimal8: VariantDecimal8) {
234        self.append_primitive_header(VariantPrimitiveType::Decimal8);
235        self.append_u8(decimal8.scale());
236        self.append_slice(&decimal8.integer().to_le_bytes());
237    }
238
239    fn append_decimal16(&mut self, decimal16: VariantDecimal16) {
240        self.append_primitive_header(VariantPrimitiveType::Decimal16);
241        self.append_u8(decimal16.scale());
242        self.append_slice(&decimal16.integer().to_le_bytes());
243    }
244
245    fn append_binary(&mut self, value: &[u8]) {
246        self.append_primitive_header(VariantPrimitiveType::Binary);
247        self.append_slice(&(value.len() as u32).to_le_bytes());
248        self.append_slice(value);
249    }
250
251    fn append_short_string(&mut self, value: ShortString) {
252        let inner = value.0;
253        self.append_u8(short_string_header(inner.len()));
254        self.append_slice(inner.as_bytes());
255    }
256
257    fn append_string(&mut self, value: &str) {
258        self.append_primitive_header(VariantPrimitiveType::String);
259        self.append_slice(&(value.len() as u32).to_le_bytes());
260        self.append_slice(value.as_bytes());
261    }
262
263    fn append_object<S: BuilderSpecificState>(state: ParentState<'_, S>, obj: VariantObject) {
264        let mut object_builder = ObjectBuilder::new(state, false);
265        object_builder.extend(obj.iter());
266        object_builder.finish();
267    }
268
269    fn try_append_object<S: BuilderSpecificState>(
270        state: ParentState<'_, S>,
271        obj: VariantObject,
272    ) -> Result<(), ArrowError> {
273        let mut object_builder = ObjectBuilder::new(state, false);
274
275        for res in obj.iter_try() {
276            let (field_name, value) = res?;
277            object_builder.try_insert(field_name, value)?;
278        }
279
280        object_builder.finish();
281        Ok(())
282    }
283
284    fn append_list<S: BuilderSpecificState>(state: ParentState<'_, S>, list: VariantList) {
285        let mut list_builder = ListBuilder::new(state, false);
286        list_builder.extend(list.iter());
287        list_builder.finish();
288    }
289
290    fn try_append_list<S: BuilderSpecificState>(
291        state: ParentState<'_, S>,
292        list: VariantList,
293    ) -> Result<(), ArrowError> {
294        let mut list_builder = ListBuilder::new(state, false);
295        for res in list.iter_try() {
296            let value = res?;
297            list_builder.try_append_value(value)?;
298        }
299
300        list_builder.finish();
301
302        Ok(())
303    }
304
305    /// Returns the current size of the underlying buffer
306    pub fn offset(&self) -> usize {
307        self.0.len()
308    }
309
310    /// Appends a variant to the builder.
311    ///
312    /// # Panics
313    ///
314    /// This method will panic if the variant contains duplicate field names in objects
315    /// when validation is enabled. For a fallible version, use [`ValueBuilder::try_append_variant`]
316    pub fn append_variant<S: BuilderSpecificState>(
317        mut state: ParentState<'_, S>,
318        variant: Variant<'_, '_>,
319    ) {
320        variant_append_value!(
321            state.value_builder(),
322            variant,
323            Variant::Object(obj) => return Self::append_object(state, obj),
324            Variant::List(list) => return Self::append_list(state, list)
325        );
326        state.finish();
327    }
328
329    /// Tries to append a variant to the provided [`ParentState`] instance.
330    ///
331    /// The attempt fails if the variant contains duplicate field names in objects when validation
332    /// is enabled.
333    pub fn try_append_variant<S: BuilderSpecificState>(
334        mut state: ParentState<'_, S>,
335        variant: Variant<'_, '_>,
336    ) -> Result<(), ArrowError> {
337        variant_append_value!(
338            state.value_builder(),
339            variant,
340            Variant::Object(obj) => return Self::try_append_object(state, obj),
341            Variant::List(list) => return Self::try_append_list(state, list)
342        );
343        state.finish();
344        Ok(())
345    }
346
347    /// Appends a variant to the buffer by copying raw bytes when possible.
348    ///
349    /// For objects and lists, this directly copies their underlying byte representation instead of
350    /// performing a logical copy and without touching the metadata builder. For other variant
351    /// types, this falls back to the standard append behavior.
352    ///
353    /// The caller must ensure that the metadata dictionary is already built and correct for
354    /// any objects or lists being appended.
355    pub fn append_variant_bytes<S: BuilderSpecificState>(
356        mut state: ParentState<'_, S>,
357        variant: Variant<'_, '_>,
358    ) {
359        let builder = state.value_builder();
360        variant_append_value!(
361            builder,
362            variant,
363            Variant::Object(obj) => builder.append_slice(obj.value),
364            Variant::List(list) => builder.append_slice(list.value)
365        );
366        state.finish();
367    }
368}
369
370/// A trait for managing state specific to different builder types.
371pub trait BuilderSpecificState: std::fmt::Debug {
372    /// Called by [`ParentState::finish`] to apply any pending builder-specific changes.
373    ///
374    /// The provided implementation does nothing by default.
375    ///
376    /// Parameters:
377    /// - `metadata_builder`: The metadata builder that was used
378    /// - `value_builder`: The value builder that was used
379    fn finish(
380        &mut self,
381        _metadata_builder: &mut dyn MetadataBuilder,
382        _value_builder: &mut ValueBuilder,
383    ) {
384    }
385
386    /// Called by [`ParentState::drop`] to revert any changes that were eagerly applied, if
387    /// [`ParentState::finish`] was never invoked.
388    ///
389    /// The provided implementation does nothing by default.
390    ///
391    /// The base [`ParentState`] will handle rolling back the value and metadata builders,
392    /// but builder-specific state may need to revert its own changes.
393    fn rollback(&mut self) {}
394}
395
396/// Empty no-op implementation for top-level variant building
397impl BuilderSpecificState for () {}
398
399/// Tracks information needed to correctly finalize a nested builder.
400///
401/// A child builder has no effect on its parent unless/until its `finalize` method is called, at
402/// which point the child appends the new value to the parent. As a (desirable) side effect,
403/// creating a parent state instance captures mutable references to a subset of the parent's fields,
404/// rendering the parent object completely unusable until the parent state goes out of scope. This
405/// ensures that at most one child builder can exist at a time.
406///
407/// The redundancy in `value_builder` and `metadata_builder` is because all the references come from
408/// the parent, and we cannot "split" a mutable reference across two objects (parent state and the
409/// child builder that uses it). So everything has to be here.
410#[derive(Debug)]
411pub struct ParentState<'a, S: BuilderSpecificState> {
412    pub(crate) value_builder: &'a mut ValueBuilder,
413    pub(crate) saved_value_builder_offset: usize,
414    pub(crate) metadata_builder: &'a mut dyn MetadataBuilder,
415    pub(crate) saved_metadata_builder_dict_size: usize,
416    pub(crate) builder_state: S,
417    pub(crate) finished: bool,
418}
419
420impl<'a, S: BuilderSpecificState> ParentState<'a, S> {
421    /// Creates a new ParentState instance. The value and metadata builder
422    /// state is checkpointed and will roll back on drop, unless [`Self::finish`] is called. The
423    /// builder-specific state is governed by its own `finish` and `rollback` calls.
424    pub fn new(
425        value_builder: &'a mut ValueBuilder,
426        metadata_builder: &'a mut dyn MetadataBuilder,
427        builder_state: S,
428    ) -> Self {
429        Self {
430            saved_value_builder_offset: value_builder.offset(),
431            value_builder,
432            saved_metadata_builder_dict_size: metadata_builder.num_field_names(),
433            metadata_builder,
434            builder_state,
435            finished: false,
436        }
437    }
438
439    /// Marks the insertion as having succeeded and invokes
440    /// [`BuilderSpecificState::finish`]. Internal state will no longer roll back on drop.
441    pub fn finish(&mut self) {
442        self.builder_state
443            .finish(self.metadata_builder, self.value_builder);
444        self.finished = true
445    }
446
447    // Rolls back value and metadata builder changes and invokes [`BuilderSpecificState::rollback`].
448    fn rollback(&mut self) {
449        if self.finished {
450            return;
451        }
452
453        self.value_builder
454            .inner_mut()
455            .truncate(self.saved_value_builder_offset);
456        self.metadata_builder
457            .truncate_field_names(self.saved_metadata_builder_dict_size);
458        self.builder_state.rollback();
459    }
460
461    // Useful because e.g. `let b = self.value_builder;` fails compilation.
462    pub(crate) fn value_builder(&mut self) -> &mut ValueBuilder {
463        self.value_builder
464    }
465
466    // Useful because e.g. `let b = self.metadata_builder;` fails compilation.
467    pub(crate) fn metadata_builder(&mut self) -> &mut dyn MetadataBuilder {
468        self.metadata_builder
469    }
470}
471
472impl<'a> ParentState<'a, ()> {
473    /// Creates a new instance suitable for a top-level variant builder
474    /// (e.g. [`VariantBuilder`]). The value and metadata builder state is checkpointed and will
475    /// roll back on drop, unless [`Self::finish`] is called.
476    pub fn variant(
477        value_builder: &'a mut ValueBuilder,
478        metadata_builder: &'a mut dyn MetadataBuilder,
479    ) -> Self {
480        Self::new(value_builder, metadata_builder, ())
481    }
482}
483
484/// Automatically rolls back any unfinished `ParentState`.
485impl<S: BuilderSpecificState> Drop for ParentState<'_, S> {
486    fn drop(&mut self) {
487        self.rollback()
488    }
489}
490
491/// Top level builder for [`Variant`] values
492///
493/// `VariantBuilder` builds a single, self-contained [`Variant`] value -- useful
494/// for one-off values and unit tests. To build an array (column) of variants,
495/// one per input row, use [`VariantArrayBuilder`] from the
496/// `parquet-variant-compute` crate rather than a `VariantBuilder` per row.
497///
498/// [`VariantArrayBuilder`]: https://docs.rs/parquet-variant-compute/latest/parquet_variant_compute/struct.VariantArrayBuilder.html
499///
500/// # Example: create a Primitive Int8
501/// ```
502/// # use parquet_variant::{Variant, VariantBuilder};
503/// let mut builder = VariantBuilder::new();
504/// builder.append_value(Variant::Int8(42));
505/// // Finish the builder to get the metadata and value
506/// let (metadata, value) = builder.finish();
507/// // use the Variant API to verify the result
508/// let variant = Variant::try_new(&metadata, &value).unwrap();
509/// assert_eq!(variant, Variant::Int8(42));
510/// ```
511///
512/// # Example: Create a [`Variant::Object`]
513///
514/// This example shows how to create an object with two fields:
515/// ```json
516/// {
517///  "first_name": "Jiaying",
518///  "last_name": "Li"
519/// }
520/// ```
521///
522/// ```
523/// # use parquet_variant::{Variant, VariantBuilder};
524/// let mut builder = VariantBuilder::new();
525/// // Create an object builder that will write fields to the object
526/// let mut object_builder = builder.new_object();
527/// object_builder.insert("first_name", "Jiaying");
528/// object_builder.insert("last_name", "Li");
529/// object_builder.finish(); // call finish to finalize the object
530/// // Finish the builder to get the metadata and value
531/// let (metadata, value) = builder.finish();
532/// // use the Variant API to verify the result
533/// let variant = Variant::try_new(&metadata, &value).unwrap();
534/// let variant_object = variant.as_object().unwrap();
535/// assert_eq!(
536///   variant_object.get("first_name"),
537///   Some(Variant::from("Jiaying"))
538/// );
539/// assert_eq!(
540///   variant_object.get("last_name"),
541///   Some(Variant::from("Li"))
542/// );
543/// ```
544///
545///
546/// You can also use the [`ObjectBuilder::with_field`] to add fields to the
547/// object
548/// ```
549/// # use parquet_variant::{Variant, VariantBuilder};
550/// // build the same object as above
551/// let mut builder = VariantBuilder::new();
552/// builder.new_object()
553///   .with_field("first_name", "Jiaying")
554///   .with_field("last_name", "Li")
555///   .finish();
556/// let (metadata, value) = builder.finish();
557/// let variant = Variant::try_new(&metadata, &value).unwrap();
558/// let variant_object = variant.as_object().unwrap();
559/// assert_eq!(
560///   variant_object.get("first_name"),
561///   Some(Variant::from("Jiaying"))
562/// );
563/// assert_eq!(
564///   variant_object.get("last_name"),
565///   Some(Variant::from("Li"))
566/// );
567/// ```
568/// # Example: Create a [`Variant::List`] (an Array)
569///
570/// This example shows how to create an array of integers: `[1, 2, 3]`.
571/// ```
572///  # use parquet_variant::{Variant, VariantBuilder};
573///  let mut builder = VariantBuilder::new();
574///  // Create a builder that will write elements to the list
575///  let mut list_builder = builder.new_list();
576///  list_builder.append_value(1i8);
577///  list_builder.append_value(2i8);
578///  list_builder.append_value(3i8);
579/// // call finish to finalize the list
580///  list_builder.finish();
581/// // Finish the builder to get the metadata and value
582/// let (metadata, value) = builder.finish();
583/// // use the Variant API to verify the result
584/// let variant = Variant::try_new(&metadata, &value).unwrap();
585/// let variant_list = variant.as_list().unwrap();
586/// // Verify the list contents
587/// assert_eq!(variant_list.get(0).unwrap(), Variant::Int8(1));
588/// assert_eq!(variant_list.get(1).unwrap(), Variant::Int8(2));
589/// assert_eq!(variant_list.get(2).unwrap(), Variant::Int8(3));
590/// ```
591///
592/// You can also use the [`ListBuilder::with_value`] to append values to the
593/// list.
594/// ```
595///  # use parquet_variant::{Variant, VariantBuilder};
596///  let mut builder = VariantBuilder::new();
597///  builder.new_list()
598///      .with_value(1i8)
599///      .with_value(2i8)
600///      .with_value(3i8)
601///      .finish();
602/// let (metadata, value) = builder.finish();
603/// let variant = Variant::try_new(&metadata, &value).unwrap();
604/// let variant_list = variant.as_list().unwrap();
605/// assert_eq!(variant_list.get(0).unwrap(), Variant::Int8(1));
606/// assert_eq!(variant_list.get(1).unwrap(), Variant::Int8(2));
607/// assert_eq!(variant_list.get(2).unwrap(), Variant::Int8(3));
608/// ```
609///
610/// # Example: [`Variant::List`] of  [`Variant::Object`]s
611///
612/// This example shows how to create an list of objects:
613/// ```json
614/// [
615///   {
616///      "id": 1,
617///      "type": "Cauliflower"
618///   },
619///   {
620///      "id": 2,
621///      "type": "Beets"
622///   }
623/// ]
624/// ```
625/// ```
626/// use parquet_variant::{Variant, VariantBuilder};
627/// let mut builder = VariantBuilder::new();
628///
629/// // Create a builder that will write elements to the list
630/// let mut list_builder = builder.new_list();
631///
632/// {
633///     let mut object_builder = list_builder.new_object();
634///     object_builder.insert("id", 1);
635///     object_builder.insert("type", "Cauliflower");
636///     object_builder.finish();
637/// }
638///
639/// {
640///     let mut object_builder = list_builder.new_object();
641///     object_builder.insert("id", 2);
642///     object_builder.insert("type", "Beets");
643///     object_builder.finish();
644/// }
645///
646/// list_builder.finish();
647/// // Finish the builder to get the metadata and value
648/// let (metadata, value) = builder.finish();
649/// // use the Variant API to verify the result
650/// let variant = Variant::try_new(&metadata, &value).unwrap();
651/// let variant_list = variant.as_list().unwrap();
652///
653///
654/// let obj1_variant = variant_list.get(0).unwrap();
655/// let obj1 = obj1_variant.as_object().unwrap();
656/// assert_eq!(
657///     obj1.get("id"),
658///     Some(Variant::from(1))
659/// );
660/// assert_eq!(
661///     obj1.get("type"),
662///     Some(Variant::from("Cauliflower"))
663/// );
664///
665/// let obj2_variant = variant_list.get(1).unwrap();
666/// let obj2 = obj2_variant.as_object().unwrap();
667///
668/// assert_eq!(
669///     obj2.get("id"),
670///     Some(Variant::from(2))
671/// );
672/// assert_eq!(
673///     obj2.get("type"),
674///     Some(Variant::from("Beets"))
675/// );
676///
677/// ```
678/// # Example: Unique Field Validation
679///
680/// This example shows how enabling unique field validation will cause an error
681/// if the same field is inserted more than once.
682/// ```
683/// # use parquet_variant::VariantBuilder;
684/// #
685/// let mut builder = VariantBuilder::new().with_validate_unique_fields(true);
686///
687/// // When validation is enabled, try_with_field will return an error
688/// let result = builder
689///     .new_object()
690///     .with_field("a", 1)
691///     .try_with_field("a", 2);
692/// assert!(result.is_err());
693/// ```
694///
695/// # Example: Sorted dictionaries
696///
697/// This example shows how to create a [`VariantBuilder`] with a pre-sorted field dictionary
698/// to improve field access performance when reading [`Variant`] objects.
699///
700/// You can use [`VariantBuilder::with_field_names`] to add multiple field names at once:
701/// ```
702/// use parquet_variant::{Variant, VariantBuilder};
703/// let mut builder = VariantBuilder::new()
704///     .with_field_names(["age", "name", "score"].into_iter());
705///
706/// let mut obj = builder.new_object();
707/// obj.insert("name", "Alice");
708/// obj.insert("age", 30);
709/// obj.insert("score", 95.5);
710/// obj.finish();
711///
712/// let (metadata, value) = builder.finish();
713/// let variant = Variant::try_new(&metadata, &value).unwrap();
714/// ```
715///
716/// Alternatively, you can use [`VariantBuilder::add_field_name`] to add field names one by one:
717/// ```
718/// use parquet_variant::{Variant, VariantBuilder};
719/// let mut builder = VariantBuilder::new();
720/// builder.add_field_name("age"); // field id = 0
721/// builder.add_field_name("name"); // field id = 1
722/// builder.add_field_name("score"); // field id = 2
723///
724/// let mut obj = builder.new_object();
725/// obj.insert("name", "Bob"); // field id = 3
726/// obj.insert("age", 25);
727/// obj.insert("score", 88.0);
728/// obj.finish();
729///
730/// let (metadata, value) = builder.finish();
731/// let variant = Variant::try_new(&metadata, &value).unwrap();
732/// ```
733#[derive(Default, Debug)]
734pub struct VariantBuilder {
735    value_builder: ValueBuilder,
736    metadata_builder: WritableMetadataBuilder,
737    validate_unique_fields: bool,
738}
739
740impl VariantBuilder {
741    /// Create a new VariantBuilder with new underlying buffers
742    pub fn new() -> Self {
743        Self {
744            value_builder: ValueBuilder::new(),
745            metadata_builder: WritableMetadataBuilder::default(),
746            validate_unique_fields: false,
747        }
748    }
749
750    /// Create a new VariantBuilder with pre-existing [`VariantMetadata`].
751    pub fn with_metadata(mut self, metadata: VariantMetadata) -> Self {
752        self.metadata_builder.extend(metadata.iter());
753
754        self
755    }
756
757    /// Enables validation of unique field keys in nested objects.
758    ///
759    /// This setting is propagated to all [`ObjectBuilder`]s created through this [`VariantBuilder`]
760    /// (including via any [`ListBuilder`]); see [`ObjectBuilder::with_validate_unique_fields`]
761    /// for how a duplicate key is reported.
762    pub fn with_validate_unique_fields(mut self, validate_unique_fields: bool) -> Self {
763        self.validate_unique_fields = validate_unique_fields;
764        self
765    }
766
767    /// This method pre-populates the field name directory in the Variant metadata with
768    /// the specific field names, in order.
769    ///
770    /// You can use this to pre-populate a [`VariantBuilder`] with a sorted dictionary if you
771    /// know the field names beforehand. Sorted dictionaries can accelerate field access when
772    /// reading [`Variant`]s.
773    pub fn with_field_names<'a>(mut self, field_names: impl IntoIterator<Item = &'a str>) -> Self {
774        self.metadata_builder.extend(field_names);
775
776        self
777    }
778
779    /// Builder-style API for appending a value to the list and returning self to enable method chaining.
780    ///
781    /// # Panics
782    ///
783    /// This method will panic if the variant contains duplicate field names in objects
784    /// when validation is enabled. For a fallible version, use [`ListBuilder::try_with_value`].
785    pub fn with_value<'m, 'd, T: Into<Variant<'m, 'd>>>(mut self, value: T) -> Self {
786        self.append_value(value);
787        self
788    }
789
790    /// Builder-style API for appending a value to the list and returns self for method chaining.
791    ///
792    /// This is the fallible version of [`ListBuilder::with_value`].
793    pub fn try_with_value<'m, 'd, T: Into<Variant<'m, 'd>>>(
794        mut self,
795        value: T,
796    ) -> Result<Self, ArrowError> {
797        self.try_append_value(value)?;
798        Ok(self)
799    }
800
801    /// This method reserves capacity for field names in the Variant metadata,
802    /// which can improve performance when you know the approximate number of unique field
803    /// names that will be used across all objects in the [`Variant`].
804    pub fn reserve(&mut self, capacity: usize) {
805        self.metadata_builder.field_names.reserve(capacity);
806    }
807
808    /// Adds a single field name to the field name directory in the Variant metadata.
809    ///
810    /// This method does the same thing as [`VariantBuilder::with_field_names`] but adds one field name at a time.
811    pub fn add_field_name(&mut self, field_name: &str) {
812        self.metadata_builder.upsert_field_name(field_name);
813    }
814
815    /// Returns true if a top-level variant value has already been written to this builder.
816    ///
817    /// A [`VariantBuilder`] holds exactly one top-level variant value. Any committed top-level
818    /// value leaves bytes in the value buffer; a child builder dropped without `finish()` has
819    /// its bytes rolled back by [`ParentState`], so the offset is a faithful indicator.
820    #[inline]
821    fn has_top_level_value(&self) -> bool {
822        self.value_builder.offset() != 0
823    }
824
825    #[inline]
826    fn ensure_no_top_level_value(&self) {
827        if self.has_top_level_value() {
828            top_level_value_panic();
829        }
830    }
831
832    #[inline]
833    fn check_no_top_level_value(&self) -> Result<(), ArrowError> {
834        if self.has_top_level_value() {
835            return Err(top_level_value_error());
836        }
837        Ok(())
838    }
839
840    /// Create an [`ListBuilder`] for creating [`Variant::List`] values.
841    ///
842    /// See the examples on [`VariantBuilder`] for usage.
843    ///
844    /// # Panics
845    ///
846    /// Panics if a top-level variant value has already been written to this builder. For a
847    /// fallible version, use [`VariantBuilder::try_new_list`].
848    pub fn new_list(&mut self) -> ListBuilder<'_, ()> {
849        self.try_new_list().unwrap()
850    }
851
852    /// Create an [`ListBuilder`] for creating [`Variant::List`] values.
853    ///
854    /// Returns an error if a top-level variant value has already been written to this builder.
855    pub fn try_new_list(&mut self) -> Result<ListBuilder<'_, ()>, ArrowError> {
856        self.check_no_top_level_value()?;
857        let parent_state =
858            ParentState::variant(&mut self.value_builder, &mut self.metadata_builder);
859        Ok(ListBuilder::new(parent_state, self.validate_unique_fields))
860    }
861
862    /// Create an [`ObjectBuilder`] for creating [`Variant::Object`] values.
863    ///
864    /// See the examples on [`VariantBuilder`] for usage.
865    ///
866    /// # Panics
867    ///
868    /// Panics if a top-level variant value has already been written to this builder. For a
869    /// fallible version, use [`VariantBuilder::try_new_object`].
870    pub fn new_object(&mut self) -> ObjectBuilder<'_, ()> {
871        self.try_new_object().unwrap()
872    }
873
874    /// Create an [`ObjectBuilder`] for creating [`Variant::Object`] values.
875    ///
876    /// Returns an error if a top-level variant value has already been written to this builder.
877    pub fn try_new_object(&mut self) -> Result<ObjectBuilder<'_, ()>, ArrowError> {
878        self.check_no_top_level_value()?;
879        let parent_state =
880            ParentState::variant(&mut self.value_builder, &mut self.metadata_builder);
881        Ok(ObjectBuilder::new(
882            parent_state,
883            self.validate_unique_fields,
884        ))
885    }
886
887    /// Append a value to the builder.
888    ///
889    /// # Panics
890    ///
891    /// Panics if a top-level variant value has already been written to this builder, or if the
892    /// variant contains duplicate field names in objects when validation is enabled. For a
893    /// fallible version, use [`VariantBuilder::try_append_value`].
894    ///
895    /// # Example
896    /// ```
897    /// # use parquet_variant::{Variant, VariantBuilder};
898    /// let mut builder = VariantBuilder::new();
899    /// // most primitive types can be appended directly as they implement `Into<Variant>`
900    /// builder.append_value(42i8);
901    /// ```
902    pub fn append_value<'m, 'd, T: Into<Variant<'m, 'd>>>(&mut self, value: T) {
903        self.ensure_no_top_level_value();
904        let state = ParentState::variant(&mut self.value_builder, &mut self.metadata_builder);
905        ValueBuilder::append_variant(state, value.into())
906    }
907
908    /// Append a value to the builder.
909    ///
910    /// Returns an error if a top-level variant value has already been written to this builder.
911    pub fn try_append_value<'m, 'd, T: Into<Variant<'m, 'd>>>(
912        &mut self,
913        value: T,
914    ) -> Result<(), ArrowError> {
915        self.check_no_top_level_value()?;
916        let state = ParentState::variant(&mut self.value_builder, &mut self.metadata_builder);
917        ValueBuilder::try_append_variant(state, value.into())
918    }
919
920    /// Appends a variant value to the builder by copying raw bytes when possible.
921    ///
922    /// For objects and lists, this directly copies their underlying byte representation instead of
923    /// performing a logical copy and without touching the metadata builder. For other variant
924    /// types, this falls back to the standard append behavior.
925    ///
926    /// The caller must ensure that the metadata dictionary entries are already built and correct for
927    /// any objects or lists being appended.
928    ///
929    /// # Panics
930    ///
931    /// Panics if a top-level variant value has already been written to this builder. For a
932    /// fallible version, use [`VariantBuilder::try_append_value_bytes`].
933    pub fn append_value_bytes<'m, 'd>(&mut self, value: impl Into<Variant<'m, 'd>>) {
934        self.try_append_value_bytes(value).unwrap()
935    }
936
937    /// Tries to append a variant value to the builder by copying raw bytes when possible.
938    ///
939    /// This is the fallible version of [`VariantBuilder::append_value_bytes`]. Returns an error
940    /// if a top-level variant value has already been written to this builder.
941    pub fn try_append_value_bytes<'m, 'd>(
942        &mut self,
943        value: impl Into<Variant<'m, 'd>>,
944    ) -> Result<(), ArrowError> {
945        self.check_no_top_level_value()?;
946        let state = ParentState::variant(&mut self.value_builder, &mut self.metadata_builder);
947        ValueBuilder::append_variant_bytes(state, value.into());
948        Ok(())
949    }
950
951    /// Finish the builder and return the metadata and value buffers.
952    ///
953    /// # Panics
954    ///
955    /// Panics if no top-level variant value has been appended. For a fallible version, use
956    /// [`VariantBuilder::try_finish`].
957    pub fn finish(self) -> (Vec<u8>, Vec<u8>) {
958        self.try_finish().expect(EMPTY_BUILDER_MSG)
959    }
960
961    /// Finish the builder and return the metadata and value buffers.
962    ///
963    /// Returns an error if no top-level variant value has been appended.
964    pub fn try_finish(mut self) -> Result<(Vec<u8>, Vec<u8>), ArrowError> {
965        if !self.has_top_level_value() {
966            return Err(empty_builder_error());
967        }
968        self.metadata_builder.finish();
969        Ok((
970            self.metadata_builder.into_inner(),
971            self.value_builder.into_inner(),
972        ))
973    }
974}
975
976/// Extends [`VariantBuilder`] to help building nested [`Variant`]s
977///
978/// Allows users to append values to a [`VariantBuilder`], [`ListBuilder`] or
979/// [`ObjectBuilder`]. using the same interface.
980pub trait VariantBuilderExt {
981    /// The builder specific state used by nested builders
982    type State<'a>: BuilderSpecificState + 'a
983    where
984        Self: 'a;
985
986    /// Appends a NULL value to this builder. The semantics depend on the implementation, but will
987    /// often translate to appending a [`Variant::Null`] value.
988    fn append_null(&mut self);
989
990    /// Appends a new variant value to this builder. See e.g. [`VariantBuilder::append_value`].
991    fn append_value<'m, 'v>(&mut self, value: impl Into<Variant<'m, 'v>>);
992
993    /// Creates a nested list builder. See e.g. [`VariantBuilder::new_list`]. Panics if the nested
994    /// builder cannot be created, see e.g. [`ObjectBuilder::new_list`].
995    fn new_list(&mut self) -> ListBuilder<'_, Self::State<'_>> {
996        self.try_new_list().unwrap()
997    }
998
999    /// Creates a nested object builder. See e.g. [`VariantBuilder::new_object`]. Panics if the
1000    /// nested builder cannot be created, see e.g. [`ObjectBuilder::new_object`].
1001    fn new_object(&mut self) -> ObjectBuilder<'_, Self::State<'_>> {
1002        self.try_new_object().unwrap()
1003    }
1004
1005    /// Creates a nested list builder. See e.g. [`VariantBuilder::new_list`]. Returns an error if
1006    /// the nested builder cannot be created, see e.g. [`ObjectBuilder::try_new_list`].
1007    fn try_new_list(&mut self) -> Result<ListBuilder<'_, Self::State<'_>>, ArrowError>;
1008
1009    /// Creates a nested object builder. See e.g. [`VariantBuilder::new_object`]. Returns an error
1010    /// if the nested builder cannot be created, see e.g. [`ObjectBuilder::try_new_object`].
1011    fn try_new_object(&mut self) -> Result<ObjectBuilder<'_, Self::State<'_>>, ArrowError>;
1012}
1013
1014impl VariantBuilderExt for VariantBuilder {
1015    type State<'a>
1016        = ()
1017    where
1018        Self: 'a;
1019
1020    /// Variant values cannot encode NULL, only [`Variant::Null`]. This is different from the column
1021    /// that holds variant values being NULL at some positions.
1022    fn append_null(&mut self) {
1023        self.append_value(Variant::Null);
1024    }
1025    fn append_value<'m, 'v>(&mut self, value: impl Into<Variant<'m, 'v>>) {
1026        self.append_value(value);
1027    }
1028
1029    fn try_new_list(&mut self) -> Result<ListBuilder<'_, Self::State<'_>>, ArrowError> {
1030        self.try_new_list()
1031    }
1032
1033    fn try_new_object(&mut self) -> Result<ObjectBuilder<'_, Self::State<'_>>, ArrowError> {
1034        self.try_new_object()
1035    }
1036}
1037
1038#[cfg(test)]
1039mod tests {
1040    use crate::{VariantMetadata, builder::metadata::ReadOnlyMetadataBuilder};
1041
1042    use super::*;
1043    #[test]
1044    fn test_simple_usage() {
1045        test_variant_roundtrip((), Variant::Null);
1046        test_variant_roundtrip(true, Variant::BooleanTrue);
1047        test_variant_roundtrip(false, Variant::BooleanFalse);
1048        test_variant_roundtrip(42i8, Variant::Int8(42));
1049        test_variant_roundtrip(1234i16, Variant::Int16(1234));
1050        test_variant_roundtrip(123456i32, Variant::Int32(123456));
1051        test_variant_roundtrip(123456789i64, Variant::Int64(123456789));
1052        test_variant_roundtrip(1.5f32, Variant::Float(1.5));
1053        test_variant_roundtrip(2.5f64, Variant::Double(2.5));
1054        test_variant_roundtrip("hello", Variant::ShortString(ShortString("hello")));
1055
1056        // Test long string (> 63 bytes)
1057        let long_string = "This is a very long string that exceeds the short string limit of 63 bytes and should be encoded as a regular string type instead of a short string";
1058        test_variant_roundtrip(long_string, Variant::String(long_string));
1059
1060        // Test binary data
1061        let binary_data = b"binary data";
1062        test_variant_roundtrip(
1063            binary_data.as_slice(),
1064            Variant::Binary(binary_data.as_slice()),
1065        );
1066    }
1067
1068    /// Helper function to test that a value can be built and reconstructed correctly
1069    fn test_variant_roundtrip<'m, 'd, T: Into<Variant<'m, 'd>>>(input: T, expected: Variant) {
1070        let mut builder = VariantBuilder::new();
1071        builder.append_value(input);
1072        let (metadata, value) = builder.finish();
1073        let variant = Variant::try_new(&metadata, &value).unwrap_or_else(|_| {
1074            panic!("Failed to create variant from metadata and value: {metadata:?}, {value:?}")
1075        });
1076        assert_eq!(variant, expected);
1077    }
1078
1079    #[test]
1080    fn test_try_finish_empty_builder_errors() {
1081        let builder = VariantBuilder::new();
1082        let err = builder.try_finish().unwrap_err();
1083        assert!(err.to_string().contains("empty"), "unexpected error: {err}");
1084    }
1085
1086    #[test]
1087    #[should_panic(expected = "empty")]
1088    fn test_finish_empty_builder_panics() {
1089        let builder = VariantBuilder::new();
1090        let _ = builder.finish();
1091    }
1092
1093    #[test]
1094    fn test_try_append_value_after_value_errors() {
1095        let mut builder = VariantBuilder::new();
1096        builder.append_value(1i32);
1097        let err = builder.try_append_value(2i32).unwrap_err();
1098        assert!(
1099            err.to_string().contains("only one is allowed"),
1100            "unexpected error: {err}"
1101        );
1102    }
1103
1104    #[test]
1105    fn test_try_append_value_bytes_after_value_errors() {
1106        let mut builder = VariantBuilder::new();
1107        builder.append_value(1i32);
1108        let err = builder.try_append_value_bytes(2i32).unwrap_err();
1109        assert!(
1110            err.to_string().contains("only one is allowed"),
1111            "unexpected error: {err}"
1112        );
1113    }
1114
1115    #[test]
1116    fn test_try_new_list_after_value_errors() {
1117        let mut builder = VariantBuilder::new();
1118        builder.append_value(1i32);
1119        let err = builder.try_new_list().expect_err("expected error");
1120        assert!(
1121            err.to_string().contains("only one is allowed"),
1122            "unexpected error: {err}"
1123        );
1124    }
1125
1126    #[test]
1127    fn test_try_new_object_after_value_errors() {
1128        let mut builder = VariantBuilder::new();
1129        builder.append_value(1i32);
1130        let err = builder.try_new_object().expect_err("expected error");
1131        assert!(
1132            err.to_string().contains("only one is allowed"),
1133            "unexpected error: {err}"
1134        );
1135    }
1136
1137    #[test]
1138    #[should_panic(expected = "only one is allowed")]
1139    fn test_append_value_after_value_panics() {
1140        let mut builder = VariantBuilder::new();
1141        builder.append_value(1i32);
1142        builder.append_value(2i32);
1143    }
1144
1145    #[test]
1146    #[should_panic(expected = "only one is allowed")]
1147    fn test_append_value_bytes_after_value_panics() {
1148        let mut builder = VariantBuilder::new();
1149        builder.append_value(1i32);
1150        builder.append_value_bytes(2i32);
1151    }
1152
1153    #[test]
1154    #[should_panic(expected = "only one is allowed")]
1155    fn test_new_list_after_value_panics() {
1156        let mut builder = VariantBuilder::new();
1157        builder.append_value(1i32);
1158        let _ = builder.new_list();
1159    }
1160
1161    #[test]
1162    #[should_panic(expected = "only one is allowed")]
1163    fn test_new_object_after_value_panics() {
1164        let mut builder = VariantBuilder::new();
1165        builder.append_value(1i32);
1166        let _ = builder.new_object();
1167    }
1168
1169    #[test]
1170    fn test_nested_object_with_lists() {
1171        /*
1172        {
1173            "door 1": {
1174                "items": ["apple", false ]
1175            }
1176        }
1177
1178        */
1179
1180        let mut builder = VariantBuilder::new();
1181        {
1182            let mut outer_object_builder = builder.new_object();
1183            {
1184                let mut inner_object_builder = outer_object_builder.new_object("door 1");
1185
1186                // create inner_object_list
1187                inner_object_builder
1188                    .new_list("items")
1189                    .with_value("apple")
1190                    .with_value(false)
1191                    .finish();
1192
1193                inner_object_builder.finish();
1194            }
1195
1196            outer_object_builder.finish();
1197        }
1198
1199        let (metadata, value) = builder.finish();
1200        let variant = Variant::try_new(&metadata, &value).unwrap();
1201        let outer_object = variant.as_object().unwrap();
1202
1203        assert_eq!(outer_object.len(), 1);
1204        assert_eq!(outer_object.field_name(0).unwrap(), "door 1");
1205
1206        let inner_object_variant = outer_object.field(0).unwrap();
1207        let inner_object = inner_object_variant.as_object().unwrap();
1208
1209        assert_eq!(inner_object.len(), 1);
1210        assert_eq!(inner_object.field_name(0).unwrap(), "items");
1211
1212        let items_variant = inner_object.field(0).unwrap();
1213        let items_list = items_variant.as_list().unwrap();
1214
1215        assert_eq!(items_list.len(), 2);
1216        assert_eq!(items_list.get(0).unwrap(), Variant::from("apple"));
1217        assert_eq!(items_list.get(1).unwrap(), Variant::from(false));
1218    }
1219
1220    #[test]
1221    fn test_sorted_dictionary() {
1222        // check if variant metadatabuilders are equivalent from different ways of constructing them
1223        let mut variant1 = VariantBuilder::new().with_field_names(["b", "c", "d"]);
1224
1225        let mut variant2 = {
1226            let mut builder = VariantBuilder::new();
1227
1228            builder.add_field_name("b");
1229            builder.add_field_name("c");
1230            builder.add_field_name("d");
1231
1232            builder
1233        };
1234
1235        assert_eq!(
1236            variant1.metadata_builder.field_names,
1237            variant2.metadata_builder.field_names
1238        );
1239
1240        // check metadata builders say it's sorted
1241        assert!(variant1.metadata_builder.is_sorted);
1242        assert!(variant2.metadata_builder.is_sorted);
1243
1244        {
1245            // test the bad case and break the sort order
1246            variant2.add_field_name("a");
1247            assert!(!variant2.metadata_builder.is_sorted);
1248
1249            // per the spec, a variant must have a top-level value; try_finish() rejects empty
1250            let err = variant2.try_finish().unwrap_err();
1251            assert!(err.to_string().contains("empty"), "unexpected error: {err}");
1252        }
1253
1254        // write out variant1 and make sure the sorted flag is properly encoded
1255        variant1.append_value(false);
1256
1257        let (m, v) = variant1.finish();
1258        let res = Variant::try_new(&m, &v);
1259        assert!(res.is_ok());
1260
1261        let header = VariantMetadata::try_new(&m).unwrap();
1262        assert!(header.is_sorted());
1263    }
1264
1265    #[test]
1266    fn test_object_sorted_dictionary() {
1267        // predefine the list of field names
1268        let mut variant1 = VariantBuilder::new().with_field_names(["a", "b", "c"]);
1269        let mut obj = variant1.new_object();
1270
1271        obj.insert("c", true);
1272        obj.insert("a", false);
1273        obj.insert("b", ());
1274
1275        // verify the field ids are correctly
1276        let field_ids_by_insert_order = obj.fields.iter().map(|(&id, _)| id).collect::<Vec<_>>();
1277        assert_eq!(field_ids_by_insert_order, vec![2, 0, 1]);
1278
1279        // add a field name that wasn't pre-defined but doesn't break the sort order
1280        obj.insert("d", 2);
1281        obj.finish();
1282
1283        let (metadata, value) = variant1.finish();
1284        let variant = Variant::try_new(&metadata, &value).unwrap();
1285
1286        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1287        assert!(metadata.is_sorted());
1288
1289        // verify object is sorted by field name order
1290        let object = variant.as_object().unwrap();
1291        let field_names = object
1292            .iter()
1293            .map(|(field_name, _)| field_name)
1294            .collect::<Vec<_>>();
1295
1296        assert_eq!(field_names, vec!["a", "b", "c", "d"]);
1297    }
1298
1299    #[test]
1300    fn test_object_not_sorted_dictionary() {
1301        // predefine the list of field names
1302        let mut variant1 = VariantBuilder::new().with_field_names(["b", "c", "d"]);
1303        let mut obj = variant1.new_object();
1304
1305        obj.insert("c", true);
1306        obj.insert("d", false);
1307        obj.insert("b", ());
1308
1309        // verify the field ids are correctly
1310        let field_ids_by_insert_order = obj.fields.iter().map(|(&id, _)| id).collect::<Vec<_>>();
1311        assert_eq!(field_ids_by_insert_order, vec![1, 2, 0]);
1312
1313        // add a field name that wasn't pre-defined but breaks the sort order
1314        obj.insert("a", 2);
1315        obj.finish();
1316
1317        let (metadata, value) = variant1.finish();
1318        let variant = Variant::try_new(&metadata, &value).unwrap();
1319
1320        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1321        assert!(!metadata.is_sorted());
1322
1323        // verify object field names are sorted by field name order
1324        let object = variant.as_object().unwrap();
1325        let field_names = object
1326            .iter()
1327            .map(|(field_name, _)| field_name)
1328            .collect::<Vec<_>>();
1329
1330        assert_eq!(field_names, vec!["a", "b", "c", "d"]);
1331    }
1332
1333    #[test]
1334    fn test_building_sorted_dictionary() {
1335        let mut builder = VariantBuilder::new();
1336        assert!(!builder.metadata_builder.is_sorted);
1337        assert_eq!(builder.metadata_builder.num_field_names(), 0);
1338
1339        builder.add_field_name("a");
1340
1341        assert!(builder.metadata_builder.is_sorted);
1342        assert_eq!(builder.metadata_builder.num_field_names(), 1);
1343
1344        let builder = builder.with_field_names(["b", "c", "d"]);
1345
1346        assert!(builder.metadata_builder.is_sorted);
1347        assert_eq!(builder.metadata_builder.num_field_names(), 4);
1348
1349        let builder = builder.with_field_names(["z", "y"]);
1350        assert!(!builder.metadata_builder.is_sorted);
1351        assert_eq!(builder.metadata_builder.num_field_names(), 6);
1352    }
1353
1354    #[test]
1355    fn test_variant_builder_to_list_builder_no_finish() {
1356        // Create a list builder but never finish it
1357        let mut builder = VariantBuilder::new();
1358        let mut list_builder = builder.new_list();
1359        list_builder.append_value("hi");
1360        drop(list_builder);
1361
1362        builder.append_value(42i8);
1363
1364        // The original builder should be unchanged
1365        let (metadata, value) = builder.finish();
1366        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1367        assert!(metadata.is_empty());
1368
1369        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1370        assert_eq!(variant, Variant::Int8(42));
1371    }
1372
1373    #[test]
1374    fn test_variant_builder_to_object_builder_no_finish() {
1375        // Create an object builder but never finish it
1376        let mut builder = VariantBuilder::new();
1377        let mut object_builder = builder.new_object();
1378        object_builder.insert("name", "unknown");
1379        drop(object_builder);
1380
1381        builder.append_value(42i8);
1382
1383        // The original builder should be unchanged
1384        let (metadata, value) = builder.finish();
1385        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1386        assert!(metadata.is_empty()); // rolled back
1387
1388        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1389        assert_eq!(variant, Variant::Int8(42));
1390    }
1391
1392    #[test]
1393    fn test_list_builder_to_list_builder_inner_no_finish() {
1394        let mut builder = VariantBuilder::new();
1395        let mut list_builder = builder.new_list();
1396        list_builder.append_value(1i8);
1397
1398        // Create a nested list builder but never finish it
1399        let mut nested_list_builder = list_builder.new_list();
1400        nested_list_builder.append_value("hi");
1401        drop(nested_list_builder);
1402
1403        list_builder.append_value(2i8);
1404
1405        // The parent list should only contain the original values
1406        list_builder.finish();
1407        let (metadata, value) = builder.finish();
1408        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1409        assert!(metadata.is_empty());
1410
1411        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1412        let list = variant.as_list().unwrap();
1413        assert_eq!(list.len(), 2);
1414        assert_eq!(list.get(0).unwrap(), Variant::Int8(1));
1415        assert_eq!(list.get(1).unwrap(), Variant::Int8(2));
1416    }
1417
1418    #[test]
1419    fn test_list_builder_to_list_builder_outer_no_finish() {
1420        let mut builder = VariantBuilder::new();
1421        let mut list_builder = builder.new_list();
1422        list_builder.append_value(1i8);
1423
1424        // Create a nested list builder and finish it
1425        let mut nested_list_builder = list_builder.new_list();
1426        nested_list_builder.append_value("hi");
1427        nested_list_builder.finish();
1428
1429        // Drop the outer list builder without finishing it
1430        drop(list_builder);
1431
1432        builder.append_value(2i8);
1433
1434        // Only the second attempt should appear in the final variant
1435        let (metadata, value) = builder.finish();
1436        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1437        assert!(metadata.is_empty());
1438
1439        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1440        assert_eq!(variant, Variant::Int8(2));
1441    }
1442
1443    #[test]
1444    fn test_list_builder_to_object_builder_inner_no_finish() {
1445        let mut builder = VariantBuilder::new();
1446        let mut list_builder = builder.new_list();
1447        list_builder.append_value(1i8);
1448
1449        // Create a nested object builder but never finish it
1450        let mut nested_object_builder = list_builder.new_object();
1451        nested_object_builder.insert("name", "unknown");
1452        drop(nested_object_builder);
1453
1454        list_builder.append_value(2i8);
1455
1456        // The parent list should only contain the original values
1457        list_builder.finish();
1458        let (metadata, value) = builder.finish();
1459        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1460        assert!(metadata.is_empty());
1461
1462        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1463        let list = variant.as_list().unwrap();
1464        assert_eq!(list.len(), 2);
1465        assert_eq!(list.get(0).unwrap(), Variant::Int8(1));
1466        assert_eq!(list.get(1).unwrap(), Variant::Int8(2));
1467    }
1468
1469    #[test]
1470    fn test_list_builder_to_object_builder_outer_no_finish() {
1471        let mut builder = VariantBuilder::new();
1472        let mut list_builder = builder.new_list();
1473        list_builder.append_value(1i8);
1474
1475        // Create a nested object builder and finish it
1476        let mut nested_object_builder = list_builder.new_object();
1477        nested_object_builder.insert("name", "unknown");
1478        nested_object_builder.finish();
1479
1480        // Drop the outer list builder without finishing it
1481        drop(list_builder);
1482
1483        builder.append_value(2i8);
1484
1485        // Only the second attempt should appear in the final variant
1486        let (metadata, value) = builder.finish();
1487        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1488        assert!(metadata.is_empty()); // rolled back
1489
1490        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1491        assert_eq!(variant, Variant::Int8(2));
1492    }
1493
1494    #[test]
1495    fn test_object_builder_to_list_builder_inner_no_finish() {
1496        let mut builder = VariantBuilder::new();
1497        let mut object_builder = builder.new_object();
1498        object_builder.insert("first", 1i8);
1499
1500        // Create a nested list builder but never finish it
1501        let mut nested_list_builder = object_builder.new_list("nested");
1502        nested_list_builder.append_value("hi");
1503        drop(nested_list_builder);
1504
1505        object_builder.insert("second", 2i8);
1506
1507        // The parent object should only contain the original fields
1508        object_builder.finish();
1509        let (metadata, value) = builder.finish();
1510
1511        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1512        assert_eq!(metadata.len(), 2);
1513        assert_eq!(&metadata[0], "first");
1514        assert_eq!(&metadata[1], "second");
1515
1516        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1517        let obj = variant.as_object().unwrap();
1518        assert_eq!(obj.len(), 2);
1519        assert_eq!(obj.get("first"), Some(Variant::Int8(1)));
1520        assert_eq!(obj.get("second"), Some(Variant::Int8(2)));
1521    }
1522
1523    #[test]
1524    fn test_object_builder_to_list_builder_outer_no_finish() {
1525        let mut builder = VariantBuilder::new();
1526        let mut object_builder = builder.new_object();
1527        object_builder.insert("first", 1i8);
1528
1529        // Create a nested list builder and finish it
1530        let mut nested_list_builder = object_builder.new_list("nested");
1531        nested_list_builder.append_value("hi");
1532        nested_list_builder.finish();
1533
1534        // Drop the outer object builder without finishing it
1535        drop(object_builder);
1536
1537        builder.append_value(2i8);
1538
1539        // Only the second attempt should appear in the final variant
1540        let (metadata, value) = builder.finish();
1541        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1542        assert!(metadata.is_empty()); // rolled back
1543
1544        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1545        assert_eq!(variant, Variant::Int8(2));
1546    }
1547
1548    #[test]
1549    fn test_object_builder_to_object_builder_inner_no_finish() {
1550        let mut builder = VariantBuilder::new();
1551        let mut object_builder = builder.new_object();
1552        object_builder.insert("first", 1i8);
1553
1554        // Create a nested object builder but never finish it
1555        let mut nested_object_builder = object_builder.new_object("nested");
1556        nested_object_builder.insert("name", "unknown");
1557        drop(nested_object_builder);
1558
1559        object_builder.insert("second", 2i8);
1560
1561        // The parent object should only contain the original fields
1562        object_builder.finish();
1563        let (metadata, value) = builder.finish();
1564
1565        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1566        assert_eq!(metadata.len(), 2); // the fields of nested_object_builder has been rolled back
1567        assert_eq!(&metadata[0], "first");
1568        assert_eq!(&metadata[1], "second");
1569
1570        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1571        let obj = variant.as_object().unwrap();
1572        assert_eq!(obj.len(), 2);
1573        assert_eq!(obj.get("first"), Some(Variant::Int8(1)));
1574        assert_eq!(obj.get("second"), Some(Variant::Int8(2)));
1575    }
1576
1577    #[test]
1578    fn test_object_builder_to_object_builder_outer_no_finish() {
1579        let mut builder = VariantBuilder::new();
1580        let mut object_builder = builder.new_object();
1581        object_builder.insert("first", 1i8);
1582
1583        // Create a nested object builder and finish it
1584        let mut nested_object_builder = object_builder.new_object("nested");
1585        nested_object_builder.insert("name", "unknown");
1586        nested_object_builder.finish();
1587
1588        // Drop the outer object builder without finishing it
1589        drop(object_builder);
1590
1591        builder.append_value(2i8);
1592
1593        // Only the second attempt should appear in the final variant
1594        let (metadata, value) = builder.finish();
1595        let metadata = VariantMetadata::try_new(&metadata).unwrap();
1596        assert_eq!(metadata.len(), 0); // rolled back
1597
1598        let variant = Variant::try_new_with_metadata(metadata, &value).unwrap();
1599        assert_eq!(variant, Variant::Int8(2));
1600    }
1601
1602    // Make sure that we can correctly build deeply nested objects even when some of the nested
1603    // builders don't finish.
1604    #[test]
1605    fn test_append_list_object_list_object() {
1606        // An infinite counter
1607        let mut counter = 0..;
1608        let mut take = move |i| (&mut counter).take(i).collect::<Vec<_>>();
1609        let mut builder = VariantBuilder::new();
1610        let skip = 5;
1611        {
1612            let mut list = builder.new_list();
1613            for i in take(4) {
1614                let mut object = list.new_object();
1615                for i in take(4) {
1616                    let field_name = format!("field{i}");
1617                    let mut list = object.new_list(&field_name);
1618                    for i in take(3) {
1619                        let mut object = list.new_object();
1620                        for i in take(3) {
1621                            if i % skip != 0 {
1622                                object.insert(&format!("field{i}"), i);
1623                            }
1624                        }
1625                        if i % skip != 0 {
1626                            object.finish();
1627                        }
1628                    }
1629                    if i % skip != 0 {
1630                        list.finish();
1631                    }
1632                }
1633                if i % skip != 0 {
1634                    object.finish();
1635                }
1636            }
1637            list.finish();
1638        }
1639        let (metadata, value) = builder.finish();
1640        let v1 = Variant::try_new(&metadata, &value).unwrap();
1641
1642        let (metadata, value) = VariantBuilder::new().with_value(v1.clone()).finish();
1643        let v2 = Variant::try_new(&metadata, &value).unwrap();
1644
1645        assert_eq!(format!("{v1:?}"), format!("{v2:?}"));
1646    }
1647
1648    #[test]
1649    fn test_append_variant_bytes_round_trip() {
1650        // Create a complex variant with the normal builder
1651        let mut builder = VariantBuilder::new();
1652        {
1653            let mut obj = builder.new_object();
1654            obj.insert("name", "Alice");
1655            obj.insert("age", 30i32);
1656            {
1657                let mut scores_list = obj.new_list("scores");
1658                scores_list.append_value(95i32);
1659                scores_list.append_value(87i32);
1660                scores_list.append_value(92i32);
1661                scores_list.finish();
1662            }
1663            {
1664                let mut address = obj.new_object("address");
1665                address.insert("street", "123 Main St");
1666                address.insert("city", "Anytown");
1667                address.finish();
1668            }
1669            obj.finish();
1670        }
1671        let (metadata, value1) = builder.finish();
1672        let variant1 = Variant::try_new(&metadata, &value1).unwrap();
1673
1674        // Copy using the new bytes API
1675        let metadata = VariantMetadata::new(&metadata);
1676        let mut metadata = ReadOnlyMetadataBuilder::new(&metadata);
1677        let mut builder2 = ValueBuilder::new();
1678        let state = ParentState::variant(&mut builder2, &mut metadata);
1679        ValueBuilder::append_variant_bytes(state, variant1);
1680        let value2 = builder2.into_inner();
1681
1682        // The bytes should be identical, we merely copied them across.
1683        assert_eq!(value1, value2);
1684    }
1685
1686    #[test]
1687    fn test_object_insert_bytes_subset() {
1688        // Create an original object, making sure to inject the field names we'll add later.
1689        let mut builder = VariantBuilder::new().with_field_names(["new_field", "another_field"]);
1690        {
1691            let mut obj = builder.new_object();
1692            obj.insert("field1", "value1");
1693            obj.insert("field2", 42i32);
1694            obj.insert("field3", true);
1695            obj.insert("field4", "value4");
1696            obj.finish();
1697        }
1698        let (metadata1, value1) = builder.finish();
1699        let original_variant = Variant::try_new(&metadata1, &value1).unwrap();
1700        let original_obj = original_variant.as_object().unwrap();
1701
1702        // Create a new object copying subset of fields interleaved with new ones
1703        let metadata2 = VariantMetadata::new(&metadata1);
1704        let mut metadata2 = ReadOnlyMetadataBuilder::new(&metadata2);
1705        let mut builder2 = ValueBuilder::new();
1706        let state = ParentState::variant(&mut builder2, &mut metadata2);
1707        {
1708            let mut obj = ObjectBuilder::new(state, true);
1709
1710            // Copy field1 using bytes API
1711            obj.insert_bytes("field1", original_obj.get("field1").unwrap());
1712
1713            // Add new field
1714            obj.insert("new_field", "new_value");
1715
1716            // Copy field3 using bytes API
1717            obj.insert_bytes("field3", original_obj.get("field3").unwrap());
1718
1719            // Add another new field
1720            obj.insert("another_field", 99i32);
1721
1722            // Copy field2 using bytes API
1723            obj.insert_bytes("field2", original_obj.get("field2").unwrap());
1724
1725            obj.finish();
1726        }
1727        let value2 = builder2.into_inner();
1728        let result_variant = Variant::try_new(&metadata1, &value2).unwrap();
1729        let result_obj = result_variant.as_object().unwrap();
1730
1731        // Verify the object contains expected fields
1732        assert_eq!(result_obj.len(), 5);
1733        assert_eq!(
1734            result_obj.get("field1").unwrap().as_string().unwrap(),
1735            "value1"
1736        );
1737        assert_eq!(result_obj.get("field2").unwrap().as_int32().unwrap(), 42);
1738        assert!(result_obj.get("field3").unwrap().as_boolean().unwrap());
1739        assert_eq!(
1740            result_obj.get("new_field").unwrap().as_string().unwrap(),
1741            "new_value"
1742        );
1743        assert_eq!(
1744            result_obj.get("another_field").unwrap().as_int32().unwrap(),
1745            99
1746        );
1747    }
1748
1749    #[test]
1750    fn test_complex_nested_filtering_injection() {
1751        // Create a complex nested structure: object -> list -> objects. Make sure to pre-register
1752        // the extra field names we'll need later while manipulating variant bytes.
1753        let mut builder = VariantBuilder::new().with_field_names([
1754            "active_count",
1755            "active_users",
1756            "computed_score",
1757            "processed_at",
1758            "status",
1759        ]);
1760
1761        {
1762            let mut root_obj = builder.new_object();
1763            root_obj.insert("metadata", "original");
1764
1765            {
1766                let mut users_list = root_obj.new_list("users");
1767
1768                // User 1
1769                {
1770                    let mut user1 = users_list.new_object();
1771                    user1.insert("id", 1i32);
1772                    user1.insert("name", "Alice");
1773                    user1.insert("active", true);
1774                    user1.finish();
1775                }
1776
1777                // User 2
1778                {
1779                    let mut user2 = users_list.new_object();
1780                    user2.insert("id", 2i32);
1781                    user2.insert("name", "Bob");
1782                    user2.insert("active", false);
1783                    user2.finish();
1784                }
1785
1786                // User 3
1787                {
1788                    let mut user3 = users_list.new_object();
1789                    user3.insert("id", 3i32);
1790                    user3.insert("name", "Charlie");
1791                    user3.insert("active", true);
1792                    user3.finish();
1793                }
1794
1795                users_list.finish();
1796            }
1797
1798            root_obj.insert("total_count", 3i32);
1799            root_obj.finish();
1800        }
1801        let (metadata1, value1) = builder.finish();
1802        let original_variant = Variant::try_new(&metadata1, &value1).unwrap();
1803        let original_obj = original_variant.as_object().unwrap();
1804        let original_users = original_obj.get("users").unwrap();
1805        let original_users = original_users.as_list().unwrap();
1806
1807        // Create filtered/modified version: only copy active users and inject new data
1808        let metadata2 = VariantMetadata::new(&metadata1);
1809        let mut metadata2 = ReadOnlyMetadataBuilder::new(&metadata2);
1810        let mut builder2 = ValueBuilder::new();
1811        let state = ParentState::variant(&mut builder2, &mut metadata2);
1812        {
1813            let mut root_obj = ObjectBuilder::new(state, true);
1814
1815            // Copy metadata using bytes API
1816            root_obj.insert_bytes("metadata", original_obj.get("metadata").unwrap());
1817
1818            // Add processing timestamp
1819            root_obj.insert("processed_at", "2024-01-01T00:00:00Z");
1820
1821            {
1822                let mut filtered_users = root_obj.new_list("active_users");
1823
1824                // Copy only active users and inject additional data
1825                for i in 0..original_users.len() {
1826                    let user = original_users.get(i).unwrap();
1827                    let user = user.as_object().unwrap();
1828                    if user.get("active").unwrap().as_boolean().unwrap() {
1829                        {
1830                            let mut new_user = filtered_users.new_object();
1831
1832                            // Copy existing fields using bytes API
1833                            new_user.insert_bytes("id", user.get("id").unwrap());
1834                            new_user.insert_bytes("name", user.get("name").unwrap());
1835
1836                            // Inject new computed field
1837                            let user_id = user.get("id").unwrap().as_int32().unwrap();
1838                            new_user.insert("computed_score", user_id * 10);
1839
1840                            // Add status transformation (don't copy the 'active' field)
1841                            new_user.insert("status", "verified");
1842
1843                            new_user.finish();
1844                        }
1845                    }
1846                }
1847
1848                // Inject a completely new user
1849                {
1850                    let mut new_user = filtered_users.new_object();
1851                    new_user.insert("id", 999i32);
1852                    new_user.insert("name", "System User");
1853                    new_user.insert("computed_score", 0i32);
1854                    new_user.insert("status", "system");
1855                    new_user.finish();
1856                }
1857
1858                filtered_users.finish();
1859            }
1860
1861            // Update count
1862            root_obj.insert("active_count", 3i32); // 2 active + 1 new
1863
1864            root_obj.finish();
1865        }
1866        let value2 = builder2.into_inner();
1867        let result_variant = Variant::try_new(&metadata1, &value2).unwrap();
1868        let result_obj = result_variant.as_object().unwrap();
1869
1870        // Verify the filtered/modified structure
1871        assert_eq!(
1872            result_obj.get("metadata").unwrap().as_string().unwrap(),
1873            "original"
1874        );
1875        assert_eq!(
1876            result_obj.get("processed_at").unwrap().as_string().unwrap(),
1877            "2024-01-01T00:00:00Z"
1878        );
1879        assert_eq!(
1880            result_obj.get("active_count").unwrap().as_int32().unwrap(),
1881            3
1882        );
1883
1884        let active_users = result_obj.get("active_users").unwrap();
1885        let active_users = active_users.as_list().unwrap();
1886        assert_eq!(active_users.len(), 3);
1887
1888        // Verify Alice (id=1, was active)
1889        let alice = active_users.get(0).unwrap();
1890        let alice = alice.as_object().unwrap();
1891        assert_eq!(alice.get("id").unwrap().as_int32().unwrap(), 1);
1892        assert_eq!(alice.get("name").unwrap().as_string().unwrap(), "Alice");
1893        assert_eq!(alice.get("computed_score").unwrap().as_int32().unwrap(), 10);
1894        assert_eq!(
1895            alice.get("status").unwrap().as_string().unwrap(),
1896            "verified"
1897        );
1898        assert!(alice.get("active").is_none()); // This field was not copied
1899
1900        // Verify Charlie (id=3, was active) - Bob (id=2) was not active so not included
1901        let charlie = active_users.get(1).unwrap();
1902        let charlie = charlie.as_object().unwrap();
1903        assert_eq!(charlie.get("id").unwrap().as_int32().unwrap(), 3);
1904        assert_eq!(charlie.get("name").unwrap().as_string().unwrap(), "Charlie");
1905        assert_eq!(
1906            charlie.get("computed_score").unwrap().as_int32().unwrap(),
1907            30
1908        );
1909        assert_eq!(
1910            charlie.get("status").unwrap().as_string().unwrap(),
1911            "verified"
1912        );
1913
1914        // Verify injected system user
1915        let system_user = active_users.get(2).unwrap();
1916        let system_user = system_user.as_object().unwrap();
1917        assert_eq!(system_user.get("id").unwrap().as_int32().unwrap(), 999);
1918        assert_eq!(
1919            system_user.get("name").unwrap().as_string().unwrap(),
1920            "System User"
1921        );
1922        assert_eq!(
1923            system_user
1924                .get("computed_score")
1925                .unwrap()
1926                .as_int32()
1927                .unwrap(),
1928            0
1929        );
1930        assert_eq!(
1931            system_user.get("status").unwrap().as_string().unwrap(),
1932            "system"
1933        );
1934    }
1935}