From 7fb3d98f2bfaefa10874ae116903e02fd5d938a6 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 2 Aug 2023 06:24:38 -0400 Subject: [PATCH 1/6] Add `Field::new_list_item` and improve `DataType::new_list` docs --- arrow-schema/src/datatype.rs | 9 +++++++-- arrow-schema/src/field.rs | 20 +++++++++++++++++++- 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/arrow-schema/src/datatype.rs b/arrow-schema/src/datatype.rs index 4f8c8a18bd17..6a776b255b8f 100644 --- a/arrow-schema/src/datatype.rs +++ b/arrow-schema/src/datatype.rs @@ -577,9 +577,14 @@ impl DataType { } } - /// Create a List DataType default name is "item" + /// Create a [`DataType::List`] where each elements has the + /// specified type and nullability and coventional name + /// (`"item"`); + /// + /// To specify field level metadata, construct the inner `Field` + /// directly via [`Field::new`] or [`Field::new_list_item`]. 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_item(data_type, nullable))) } } diff --git a/arrow-schema/src/field.rs b/arrow-schema/src/field.rs index 00deecf06283..c36ab4ff3dc7 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, 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, by convention the inner `Field` of these + /// types is named `"item"` + /// + /// # Example + /// ``` + /// # use arrow_schema::{Field, DataType}; + /// assert_eq!( + /// Field::new("item", DataType::Int32, true), + /// Field::new_list_item(DataType::Int32, true) + /// ); + /// ``` + pub fn new_list_item(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, From 424abf22d844f2ce6b646cd69cd873df74af214b Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 3 Aug 2023 10:30:18 -0400 Subject: [PATCH 2/6] Update arrow-schema/src/datatype.rs Co-authored-by: Liang-Chi Hsieh --- arrow-schema/src/datatype.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow-schema/src/datatype.rs b/arrow-schema/src/datatype.rs index 6a776b255b8f..b42426e2e2f4 100644 --- a/arrow-schema/src/datatype.rs +++ b/arrow-schema/src/datatype.rs @@ -578,7 +578,7 @@ impl DataType { } /// Create a [`DataType::List`] where each elements has the - /// specified type and nullability and coventional name + /// specified type and nullability and conventional name /// (`"item"`); /// /// To specify field level metadata, construct the inner `Field` From 4fc2f8f1288bfd3a15334dca9bc4ba868262dd1b Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 3 Aug 2023 10:30:23 -0400 Subject: [PATCH 3/6] Update arrow-schema/src/datatype.rs Co-authored-by: Liang-Chi Hsieh --- arrow-schema/src/datatype.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow-schema/src/datatype.rs b/arrow-schema/src/datatype.rs index b42426e2e2f4..54fa3a8ced4b 100644 --- a/arrow-schema/src/datatype.rs +++ b/arrow-schema/src/datatype.rs @@ -577,7 +577,7 @@ impl DataType { } } - /// Create a [`DataType::List`] where each elements has the + /// Create a [`DataType::List`] where each element has the /// specified type and nullability and conventional name /// (`"item"`); /// From 76b1e70896988aa4f4202d493c62e4a47a8414a8 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 3 Aug 2023 10:32:19 -0400 Subject: [PATCH 4/6] rename to `new_list_field` --- arrow-schema/src/field.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/arrow-schema/src/field.rs b/arrow-schema/src/field.rs index c36ab4ff3dc7..cbaf721eec1a 100644 --- a/arrow-schema/src/field.rs +++ b/arrow-schema/src/field.rs @@ -140,10 +140,10 @@ impl Field { /// # use arrow_schema::{Field, DataType}; /// assert_eq!( /// Field::new("item", DataType::Int32, true), - /// Field::new_list_item(DataType::Int32, true) + /// Field::new_list_field(DataType::Int32, true) /// ); /// ``` - pub fn new_list_item(data_type: DataType, nullable: bool) -> Self { + pub fn new_list_field(data_type: DataType, nullable: bool) -> Self { Self::new("item", data_type, nullable) } From d8d590950e19b2facfec0208457209655225ab1e Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 3 Aug 2023 14:46:48 -0400 Subject: [PATCH 5/6] Fix compile --- arrow-schema/src/datatype.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow-schema/src/datatype.rs b/arrow-schema/src/datatype.rs index 54fa3a8ced4b..993a190a6f86 100644 --- a/arrow-schema/src/datatype.rs +++ b/arrow-schema/src/datatype.rs @@ -584,7 +584,7 @@ impl DataType { /// To specify field level metadata, construct the inner `Field` /// directly via [`Field::new`] or [`Field::new_list_item`]. pub fn new_list(data_type: DataType, nullable: bool) -> Self { - DataType::List(Arc::new(Field::new_list_item(data_type, nullable))) + DataType::List(Arc::new(Field::new_list_field(data_type, nullable))) } } From 43e1047addb8c3846a12307c5d950e150cb3d44c Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 27 Dec 2023 07:44:46 -0500 Subject: [PATCH 6/6] Fix doc bug and tweak docs --- arrow-schema/src/datatype.rs | 9 ++++----- arrow-schema/src/field.rs | 6 +++--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/arrow-schema/src/datatype.rs b/arrow-schema/src/datatype.rs index f771f7af0ae3..8ba52200c478 100644 --- a/arrow-schema/src/datatype.rs +++ b/arrow-schema/src/datatype.rs @@ -573,12 +573,11 @@ impl DataType { } } - /// Create a [`DataType::List`] where each element has the - /// specified type and nullability and conventional name - /// (`"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_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_list_field(data_type, nullable))) } diff --git a/arrow-schema/src/field.rs b/arrow-schema/src/field.rs index 82647f5aff15..eebaf0e3c1b9 100644 --- a/arrow-schema/src/field.rs +++ b/arrow-schema/src/field.rs @@ -129,11 +129,11 @@ impl Field { } } - /// Creates a new field suitable for [`DataType::List`] and + /// Creates a new `Field`` suitable for [`DataType::List`] and /// [`DataType::LargeList`] /// - /// While not required, by convention the inner `Field` of these - /// types is named `"item"` + /// While not required, this method follows the convention of naming the + /// `Field` `"item"`. /// /// # Example /// ```