@@ -631,7 +631,7 @@ impl ParentState<'_> {
631
631
/// let mut object_builder = builder.new_object();
632
632
/// object_builder.insert("first_name", "Jiaying");
633
633
/// object_builder.insert("last_name", "Li");
634
- /// object_builder.finish();
634
+ /// object_builder.finish(); // call finish to finalize the object
635
635
/// // Finish the builder to get the metadata and value
636
636
/// let (metadata, value) = builder.finish();
637
637
/// // use the Variant API to verify the result
@@ -647,6 +647,29 @@ impl ParentState<'_> {
647
647
/// );
648
648
/// ```
649
649
///
650
+ ///
651
+ /// You can also use the [`ObjectBuilder::with_field`] to add fields to the
652
+ /// object
653
+ /// ```
654
+ /// # use parquet_variant::{Variant, VariantBuilder};
655
+ /// // build the same object as above
656
+ /// let mut builder = VariantBuilder::new();
657
+ /// builder.new_object()
658
+ /// .with_field("first_name", "Jiaying")
659
+ /// .with_field("last_name", "Li")
660
+ /// .finish();
661
+ /// let (metadata, value) = builder.finish();
662
+ /// let variant = Variant::try_new(&metadata, &value).unwrap();
663
+ /// let variant_object = variant.as_object().unwrap();
664
+ /// assert_eq!(
665
+ /// variant_object.get("first_name"),
666
+ /// Some(Variant::from("Jiaying"))
667
+ /// );
668
+ /// assert_eq!(
669
+ /// variant_object.get("last_name"),
670
+ /// Some(Variant::from("Li"))
671
+ /// );
672
+ /// ```
650
673
/// # Example: Create a [`Variant::List`] (an Array)
651
674
///
652
675
/// This example shows how to create an array of integers: `[1, 2, 3]`.
@@ -846,6 +869,7 @@ impl VariantBuilder {
846
869
}
847
870
}
848
871
872
+ /// Create a new VariantBuilder with pre-existing [`VariantMetadata`].
849
873
pub fn with_metadata ( mut self , metadata : VariantMetadata ) -> Self {
850
874
self . metadata_builder . extend ( metadata. iter ( ) ) ;
851
875
@@ -1094,6 +1118,10 @@ impl<'a> ObjectBuilder<'a> {
1094
1118
1095
1119
/// Add a field with key and value to the object
1096
1120
///
1121
+ /// # See Also
1122
+ /// - [`ObjectBuilder::try_insert`] for a fallible version.
1123
+ /// - [`ObjectBuilder::with_field`] for a builder-style API.
1124
+ ///
1097
1125
/// # Panics
1098
1126
///
1099
1127
/// This method will panic if the variant contains duplicate field names in objects
@@ -1104,7 +1132,12 @@ impl<'a> ObjectBuilder<'a> {
1104
1132
1105
1133
/// Add a field with key and value to the object
1106
1134
///
1107
- /// Note: when inserting duplicate keys, the new value overwrites the previous mapping,
1135
+ /// # See Also
1136
+ /// - [`ObjectBuilder::insert`] for a infallabel version
1137
+ /// - [`ObjectBuilder::try_with_field`] for a builder-style API.
1138
+ ///
1139
+ /// # Note
1140
+ /// When inserting duplicate keys, the new value overwrites the previous mapping,
1108
1141
/// but the old value remains in the buffer, resulting in a larger variant
1109
1142
pub fn try_insert < ' m , ' d , T : Into < Variant < ' m , ' d > > > (
1110
1143
& mut self ,
@@ -1127,6 +1160,26 @@ impl<'a> ObjectBuilder<'a> {
1127
1160
Ok ( ( ) )
1128
1161
}
1129
1162
1163
+ /// Builder style API for adding a field with key and value to the object
1164
+ ///
1165
+ /// Same as [`ObjectBuilder::insert`], but returns `self` for chaining.
1166
+ pub fn with_field < ' m , ' d , T : Into < Variant < ' m , ' d > > > ( mut self , key : & str , value : T ) -> Self {
1167
+ self . insert ( key, value) ;
1168
+ self
1169
+ }
1170
+
1171
+ /// Builder style API for adding a field with key and value to the object
1172
+ ///
1173
+ /// Same as [`ObjectBuilder::try_insert`], but returns `self` for chaining.
1174
+ pub fn try_with_field < ' m , ' d , T : Into < Variant < ' m , ' d > > > (
1175
+ mut self ,
1176
+ key : & str ,
1177
+ value : T ,
1178
+ ) -> Result < Self , ArrowError > {
1179
+ self . try_insert ( key, value) ?;
1180
+ Ok ( self )
1181
+ }
1182
+
1130
1183
/// Enables validation for unique field keys when inserting into this object.
1131
1184
///
1132
1185
/// When this is enabled, calling [`ObjectBuilder::finish`] will return an error
@@ -1410,12 +1463,12 @@ mod tests {
1410
1463
fn test_object ( ) {
1411
1464
let mut builder = VariantBuilder :: new ( ) ;
1412
1465
1413
- {
1414
- let mut obj = builder . new_object ( ) ;
1415
- obj . insert ( "name" , "John" ) ;
1416
- obj . insert ( "age" , 42i8 ) ;
1417
- let _ = obj . finish ( ) ;
1418
- }
1466
+ builder
1467
+ . new_object ( )
1468
+ . with_field ( "name" , "John" )
1469
+ . with_field ( "age" , 42i8 )
1470
+ . finish ( )
1471
+ . unwrap ( ) ;
1419
1472
1420
1473
let ( metadata, value) = builder. finish ( ) ;
1421
1474
assert ! ( !metadata. is_empty( ) ) ;
@@ -1426,13 +1479,13 @@ mod tests {
1426
1479
fn test_object_field_ordering ( ) {
1427
1480
let mut builder = VariantBuilder :: new ( ) ;
1428
1481
1429
- {
1430
- let mut obj = builder . new_object ( ) ;
1431
- obj . insert ( "zebra" , "stripes" ) ; // ID = 0
1432
- obj . insert ( "apple" , "red" ) ; // ID = 1
1433
- obj . insert ( "banana" , "yellow" ) ; // ID = 2
1434
- let _ = obj . finish ( ) ;
1435
- }
1482
+ builder
1483
+ . new_object ( )
1484
+ . with_field ( "zebra" , "stripes" )
1485
+ . with_field ( "apple" , "red" )
1486
+ . with_field ( "banana" , "yellow" )
1487
+ . finish ( )
1488
+ . unwrap ( ) ;
1436
1489
1437
1490
let ( _, value) = builder. finish ( ) ;
1438
1491
@@ -1452,10 +1505,12 @@ mod tests {
1452
1505
#[ test]
1453
1506
fn test_duplicate_fields_in_object ( ) {
1454
1507
let mut builder = VariantBuilder :: new ( ) ;
1455
- let mut object_builder = builder. new_object ( ) ;
1456
- object_builder. insert ( "name" , "Ron Artest" ) ;
1457
- object_builder. insert ( "name" , "Metta World Peace" ) ;
1458
- let _ = object_builder. finish ( ) ;
1508
+ builder
1509
+ . new_object ( )
1510
+ . with_field ( "name" , "Ron Artest" )
1511
+ . with_field ( "name" , "Metta World Peace" ) // Duplicate field
1512
+ . finish ( )
1513
+ . unwrap ( ) ;
1459
1514
1460
1515
let ( metadata, value) = builder. finish ( ) ;
1461
1516
let variant = Variant :: try_new ( & metadata, & value) . unwrap ( ) ;
@@ -1572,19 +1627,19 @@ mod tests {
1572
1627
1573
1628
let mut list_builder = builder. new_list ( ) ;
1574
1629
1575
- {
1576
- let mut object_builder = list_builder . new_object ( ) ;
1577
- object_builder . insert ( "id" , 1 ) ;
1578
- object_builder . insert ( "type" , "Cauliflower" ) ;
1579
- let _ = object_builder . finish ( ) ;
1580
- }
1630
+ list_builder
1631
+ . new_object ( )
1632
+ . with_field ( "id" , 1 )
1633
+ . with_field ( "type" , "Cauliflower" )
1634
+ . finish ( )
1635
+ . unwrap ( ) ;
1581
1636
1582
- {
1583
- let mut object_builder = list_builder . new_object ( ) ;
1584
- object_builder . insert ( "id" , 2 ) ;
1585
- object_builder . insert ( "type" , "Beets" ) ;
1586
- let _ = object_builder . finish ( ) ;
1587
- }
1637
+ list_builder
1638
+ . new_object ( )
1639
+ . with_field ( "id" , 2 )
1640
+ . with_field ( "type" , "Beets" )
1641
+ . finish ( )
1642
+ . unwrap ( ) ;
1588
1643
1589
1644
list_builder. finish ( ) ;
1590
1645
@@ -1621,17 +1676,17 @@ mod tests {
1621
1676
1622
1677
let mut list_builder = builder. new_list ( ) ;
1623
1678
1624
- {
1625
- let mut object_builder = list_builder . new_object ( ) ;
1626
- object_builder . insert ( "a" , 1 ) ;
1627
- let _ = object_builder . finish ( ) ;
1628
- }
1629
-
1630
- {
1631
- let mut object_builder = list_builder . new_object ( ) ;
1632
- object_builder . insert ( "b" , 2 ) ;
1633
- let _ = object_builder . finish ( ) ;
1634
- }
1679
+ list_builder
1680
+ . new_object ( )
1681
+ . with_field ( "a" , 1 )
1682
+ . finish ( )
1683
+ . unwrap ( ) ;
1684
+
1685
+ list_builder
1686
+ . new_object ( )
1687
+ . with_field ( "b" , 2 )
1688
+ . finish ( )
1689
+ . unwrap ( ) ;
1635
1690
1636
1691
list_builder. finish ( ) ;
1637
1692
0 commit comments