You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by al...@apache.org on 2023/12/27 12:56:38 UTC

(arrow-rs) branch master updated: Add `Field::new_list_field` and improve `DataType::new_list` docs (#4627)

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

alamb 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 3cd6da0a6b Add `Field::new_list_field` and improve `DataType::new_list` docs (#4627)
3cd6da0a6b is described below

commit 3cd6da0a6b97056f3717d3491c84ec6d734aa262
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Wed Dec 27 07:56:32 2023 -0500

    Add `Field::new_list_field` and improve `DataType::new_list` docs (#4627)
    
    * Add `Field::new_list_item` and improve `DataType::new_list` docs
    
    * Update arrow-schema/src/datatype.rs
    
    Co-authored-by: Liang-Chi Hsieh <vi...@gmail.com>
    
    * Update arrow-schema/src/datatype.rs
    
    Co-authored-by: Liang-Chi Hsieh <vi...@gmail.com>
    
    * rename to `new_list_field`
    
    * Fix compile
    
    * Fix doc bug and tweak docs
    
    ---------
    
    Co-authored-by: Liang-Chi Hsieh <vi...@gmail.com>
---
 arrow-schema/src/datatype.rs |  8 ++++++--
 arrow-schema/src/field.rs    | 20 +++++++++++++++++++-
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/arrow-schema/src/datatype.rs b/arrow-schema/src/datatype.rs
index 330ae5c9e3..8ba52200c4 100644
--- a/arrow-schema/src/datatype.rs
+++ b/arrow-schema/src/datatype.rs
@@ -573,9 +573,13 @@ impl DataType {
         }
     }
 
-    /// Create a List DataType default name is "item"
+    /// Create a [`DataType::List`] with elements of the specified type
+    /// and nullability, and conventionally named inner [`Field`] (`"item"`).
+    ///
+    /// To specify field level metadata, construct the inner [`Field`]
+    /// directly via [`Field::new`] or [`Field::new_list_field`].
     pub fn new_list(data_type: DataType, nullable: bool) -> Self {
-        DataType::List(Arc::new(Field::new("item", data_type, nullable)))
+        DataType::List(Arc::new(Field::new_list_field(data_type, nullable)))
     }
 }
 
diff --git a/arrow-schema/src/field.rs b/arrow-schema/src/field.rs
index 574c024bb9..eebaf0e3c1 100644
--- a/arrow-schema/src/field.rs
+++ b/arrow-schema/src/field.rs
@@ -117,7 +117,7 @@ impl Hash for Field {
 }
 
 impl Field {
-    /// Creates a new field
+    /// Creates a new field with the given name, type, and nullability
     pub fn new(name: impl Into<String>, data_type: DataType, nullable: bool) -> Self {
         Field {
             name: name.into(),
@@ -129,6 +129,24 @@ impl Field {
         }
     }
 
+    /// Creates a new `Field`` suitable for [`DataType::List`] and
+    /// [`DataType::LargeList`]
+    ///
+    /// While not required, this method follows the convention of naming the
+    /// `Field` `"item"`.
+    ///
+    /// # Example
+    /// ```
+    /// # use arrow_schema::{Field, DataType};
+    /// assert_eq!(
+    ///   Field::new("item", DataType::Int32, true),
+    ///   Field::new_list_field(DataType::Int32, true)
+    /// );
+    /// ```
+    pub fn new_list_field(data_type: DataType, nullable: bool) -> Self {
+        Self::new("item", data_type, nullable)
+    }
+
     /// Creates a new field that has additional dictionary information
     pub fn new_dict(
         name: impl Into<String>,