[arrow-rs] branch master updated: Add builder style APIs For `Field`: `with_name`, `with_data_type` and `with_nullable` (#2024)

[tustvold]

This is an automated email from the ASF dual-hosted git repository.

tustvold pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git


The following commit(s) were added to refs/heads/master by this push:
     new 7542f7d1c Add builder style APIs For `Field`: `with_name`, 
`with_data_type` and `with_nullable` (#2024)
7542f7d1c is described below

commit 7542f7d1cb341fedec09307713bba5536e6baab6
Author: Andrew Lamb <and...@nerdnetworks.org>
AuthorDate: Fri Jul 8 10:12:19 2022 -0400

    Add builder style APIs For `Field`: `with_name`, `with_data_type` and 
`with_nullable` (#2024)
    
    * Add builder style APIs `with_name`, `with_data_type` and `with_nullable` 
to Field
    
    * Apply suggestions from code review
    
    Co-authored-by: Liang-Chi Hsieh <vii...@gmail.com>
    
    Co-authored-by: Liang-Chi Hsieh <vii...@gmail.com>
---
 arrow/src/datatypes/field.rs | 66 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 56 insertions(+), 10 deletions(-)

diff --git a/arrow/src/datatypes/field.rs b/arrow/src/datatypes/field.rs
index 5025d32a4..ade48d93d 100644
--- a/arrow/src/datatypes/field.rs
+++ b/arrow/src/datatypes/field.rs
@@ -26,9 +26,10 @@ use crate::error::{ArrowError, Result};
 
 use super::DataType;
 
-/// Contains the meta-data for a single relative type.
+/// Describes a single column in a [`Schema`](super::Schema).
 ///
-/// The `Schema` object is an ordered collection of `Field` objects.
+/// A [`Schema`](super::Schema) is an ordered collection of
+/// [`Field`] objects.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Field {
     name: String,
@@ -95,7 +96,7 @@ impl Field {
         }
     }
 
-    /// Creates a new field
+    /// Creates a new field that has additional dictionary information
     pub fn new_dict(
         name: &str,
         data_type: DataType,
@@ -144,19 +145,62 @@ impl Field {
         &self.name
     }
 
-    /// Returns an immutable reference to the `Field`'s  data-type.
+    /// Set the name of the [`Field`] and returns self.
+    ///
+    /// ```
+    /// # use arrow::datatypes::*;
+    /// let field = Field::new("c1", DataType::Int64, false)
+    ///    .with_name("c2");
+    ///
+    /// assert_eq!(field.name(), "c2");
+    /// ```
+    pub fn with_name(mut self, name: impl Into<String>) -> Self {
+        self.name = name.into();
+        self
+    }
+
+    /// Returns an immutable reference to the [`Field`]'s  [`DataType`].
     #[inline]
     pub const fn data_type(&self) -> &DataType {
         &self.data_type
     }
 
-    /// Indicates whether this `Field` supports null values.
+    /// Set [`DataType`] of the [`Field`] and returns self.
+    ///
+    /// ```
+    /// # use arrow::datatypes::*;
+    /// let field = Field::new("c1", DataType::Int64, false)
+    ///    .with_data_type(DataType::Utf8);
+    ///
+    /// assert_eq!(field.data_type(), &DataType::Utf8);
+    /// ```
+    pub fn with_data_type(mut self, data_type: DataType) -> Self {
+        self.data_type = data_type;
+        self
+    }
+
+    /// Indicates whether this [`Field`] supports null values.
     #[inline]
     pub const fn is_nullable(&self) -> bool {
         self.nullable
     }
 
-    /// Returns a (flattened) vector containing all fields contained within 
this field (including it self)
+    /// Set `nullable` of the [`Field`] and returns self.
+    ///
+    /// ```
+    /// # use arrow::datatypes::*;
+    /// let field = Field::new("c1", DataType::Int64, false)
+    ///    .with_nullable(true);
+    ///
+    /// assert_eq!(field.is_nullable(), true);
+    /// ```
+    pub fn with_nullable(mut self, nullable: bool) -> Self {
+        self.nullable = nullable;
+        self
+    }
+
+    /// Returns a (flattened) [`Vec`] containing all child [`Field`]s
+    /// within `self` contained within this field (including `self`)
     pub(crate) fn fields(&self) -> Vec<&Field> {
         let mut collected_fields = vec![self];
         collected_fields.append(&mut self._fields(&self.data_type));
@@ -491,14 +535,16 @@ impl Field {
         }
     }
 
-    /// Merge field into self if it is compatible. Struct will be merged 
recursively.
-    /// NOTE: `self` may be updated to unexpected state in case of merge 
failure.
+    /// Merge this field into self if it is compatible.
+    ///
+    /// Struct fields are merged recursively.
+    ///
+    /// NOTE: `self` may be updated to a partial / unexpected state in case of 
merge failure.
     ///
     /// Example:
     ///
     /// ```
-    /// use arrow::datatypes::*;
-    ///
+    /// # use arrow::datatypes::*;
     /// let mut field = Field::new("c1", DataType::Int64, false);
     /// assert!(field.try_merge(&Field::new("c1", DataType::Int64, 
true)).is_ok());
     /// assert!(field.is_nullable());